Migrating from Hugo

Migrating from Go-based Hugo to Rustyll? This guide will help you transition your site to Rustyll while preserving your content structure and taking advantage of Rustyll’s performance and flexibility.

Installation

First, install Rustyll using Cargo (Rust’s package manager):

# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Rustyll
cargo install rustyll

Automatic Migration

Rustyll provides a built-in migration tool for Hugo sites:

rustyll migrate --from hugo --source ./my-hugo-site --destination ./my-rustyll-site

This command will:

Convert content files and front matter
Transform Hugo templates to Liquid syntax
Adapt shortcodes to Rustyll includes
Process data files and configuration
Generate a migration report

Directory Structure Differences

Hugo	Rustyll	Notes
`content/`	Root directory (and collections)	Content organization is different
`layouts/`	`_layouts/` and `_includes/`	Templates are split by purpose
`static/`	`assets/`	Static assets live here
`data/`	`_data/`	Data files (similar functionality)
`themes/`	Themes use the same directory structure	Themes work differently
`config.toml`	`_config.yml`	Configuration uses YAML
`public/`	`_site/`	Generated site

Content Conversion

Hugo’s content structure with front matter converts to Rustyll’s approach:

<!-- Hugo (content/posts/first-post.md) -->
+++
title = "My First Post"
date = 2023-01-15T09:00:00+00:00
draft = false
tags = ["rust", "static-site"]
+++

This is my first post.

Converts to:

<!-- Rustyll (_posts/2023-01-15-first-post.md) -->
---
title: "My First Post"
date: 2023-01-15 09:00:00 +0000
tags:
  - rust
  - static-site
---

This is my first post.

Template Conversion

Go Templates to Liquid

Hugo’s Go templates convert to Rustyll’s Liquid templates:

<!-- Hugo (layouts/partials/header.html) -->

<header>
  <h1>{{ .Site.Title }}</h1>
  <nav>
    {{ range .Site.Menus.main }}
    <a href="{{ .URL }}" class="{{ if $.IsMenuCurrent "main" . }}active{{ end }}">
      {{ .Name }}
    </a>
    {{ end }}
  </nav>
</header>

Converts to:

<!-- Rustyll (_includes/header.html) -->

<header>
  <h1>{{ site.title }}</h1>
  <nav>
    
  </nav>
</header>

Shortcodes to Includes

Hugo’s shortcodes convert to Rustyll includes:

<!-- Hugo shortcode usage -->
{{< figure src="/images/sunset.jpg" title="Beautiful Sunset" >}}

Converts to:

<!-- Rustyll include usage -->
{% include figure.html src="/images/sunset.jpg" title="Beautiful Sunset" %}

With the corresponding include file:

<!-- Rustyll (_includes/figure.html) -->
<figure>
  <img src="{{ include.src }}" alt="{{ include.title }}">
  <figcaption>{{ include.title }}</figcaption>
</figure>

Configuration Conversion

Hugo’s TOML configuration converts to Rustyll’s YAML:

# Hugo (config.toml)
baseURL = "https://example.com/"
languageCode = "en-us"
title = "My Hugo Site"
theme = "my-theme"

[params]
  description = "A site built with Hugo"
  author = "Your Name"

[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
  [[menu.main]]
    name = "About"
    url = "/about/"
    weight = 2

Converts to:

# Rustyll (_config.yml)
url: https://example.com
title: My Hugo Site
description: A site built with Hugo
author: Your Name

# Menu is moved to _data/menu.yml
markdown: commonmark
sass:
  style: compressed

# Performance settings
threads: auto
incremental: true

With a corresponding data file:

# Rustyll (_data/menu.yml)
main:
  - name: Home
    url: /
    weight: 1
  - name: About
    url: /about/
    weight: 2

Content Organization

Hugo’s content organization converts to Rustyll’s collections:

Hugo	Rustyll	Notes
`content/posts/`	`_posts/`	Blog posts
`content/projects/`	`_projects/` (collection)	Custom collection
`content/about.md`	`about.md`	Pages at root level
`content/pages/`	Page files at root	Regular pages

Configure collections in _config.yml:

# Rustyll (_config.yml)
collections:
  projects:
    output: true
    permalink: /projects/:path/

Taxonomy System

Hugo’s taxonomy system converts to Rustyll’s approach:

# Hugo taxonomy configuration
[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

Convert to Rustyll collections and plugins:

# Rustyll taxonomy approach
plugins:
  - rustyll-taxonomies

taxonomies:
  categories:
    permalink: /categories/:name/
  tags:
    permalink: /tags/:name/
  series:
    permalink: /series/:name/

Data Files

Hugo’s data files convert to Rustyll’s _data directory:

// Hugo (data/team.json)
{
  "members": [
    {
      "name": "John Doe",
      "role": "Developer"
    },
    {
      "name": "Jane Smith",
      "role": "Designer"
    }
  ]
}

Converts to:

# Rustyll (_data/team.yml)
members:
  - name: John Doe
    role: Developer
  - name: Jane Smith
    role: Designer

Asset Pipeline

Hugo’s asset processing converts to Rustyll’s approach:

Hugo	Rustyll	Notes
Hugo Pipes	Asset pipeline	Similar functionality
SCSS processing	Built-in Sass	Similar syntax
Asset bundling	Asset optimization	Similar results
Fingerprinting	Asset hashing	Cache busting

Performance Considerations

Both Hugo and Rustyll focus on performance, but Rustyll offers additional options:

# Rustyll performance options
threads: auto  # Use all available CPU cores
incremental: true  # Enable incremental builds
cache:
  enabled: true
  strategy: aggressive

Comparison:

Build Speed: Both are very fast, with Hugo slightly faster for massive sites
Memory Usage: Both are efficient
Incremental Builds: Rustyll offers more granular control
Concurrency: Both use multiple CPU cores efficiently

Multilingual Support

Hugo’s multilingual setup converts to Rustyll’s approach:

# Hugo multilingual config
[languages]
  [languages.en]
    title = "My Site"
    weight = 1
  [languages.fr]
    title = "Mon Site"
    weight = 2

Converts to:

# Rustyll (_config.yml)
languages:
  - code: en
    name: English
    title: My Site
    weight: 1
  - code: fr
    name: French
    title: Mon Site
    weight: 2

Troubleshooting Common Issues

Template Syntax

If you encounter template conversion issues:

Hugo uses Go templates with {{ .Variable }} syntax
Rustyll uses Liquid with {{ variable }} syntax
Control structures are different ({{ range .Items }} vs {% for item in items %})

Front Matter Format

Hugo supports TOML, YAML, and JSON front matter:

Convert TOML (+++) and JSON front matter to YAML (---)
Adjust date formats to ISO 8601 (YYYY-MM-DD HH:MM:SS +/-TTTT)
Convert boolean values properly (draft = false to draft: false)

Content Organization

Hugo uses content sections while Rustyll uses collections:

Map each Hugo section to a Rustyll collection
Configure collection permalinks to match Hugo’s URL structure
Update templates to use Rustyll’s collection syntax

Rustyll