Migrating from Docsy

Migrating from Docsy (a Hugo documentation theme) to Rustyll? This guide will help you transition your documentation site while preserving its structure and features.

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 Docsy sites:

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

This command will:

Copy all content files
Convert Hugo/Docsy-specific front matter to Rustyll format
Transform Hugo templates and Docsy components to Liquid templates
Adjust configuration settings
Generate a migration report

Directory Structure Differences

Docsy/Hugo	Rustyll	Notes
`content/`	root directory	Content goes in the root folder in Rustyll
`layouts/`	`_layouts/` and `_includes/`	Templates are split between layouts and includes
`static/`	`assets/`	Static files go in the assets directory
`config.toml`	`_config.yml`	Configuration file (YAML format)
`themes/docsy/`	Built-in Rustyll docs theme	Docsy-specific components converted to Rustyll includes

Documentation Features

Docsy is specialized for documentation sites. Rustyll provides equivalent features:

Docsy Feature	Rustyll Equivalent
Section navigation	Hierarchical collections with navigation
Versioned docs	Collections with version prefixes
Search	Integrated search with rustyll-search plugin
Landing page components	Custom includes and layouts
Taxonomy for tags	Collections for categorization

Template Differences

Docsy Shortcodes vs. Rustyll Includes

Docsy shortcodes are converted to Rustyll includes:

Docsy/Hugo	Rustyll
`{{< alert >}}Content{{< /alert >}}`	`{% include alert.html content="Content" %}`
`{{< tabs >}}...{{< /tabs >}}`	`{% include tabs.html %}...{% include tabs-end.html %}`
`{{< cardpane >}}...{{< /cardpane >}}`	`{% include cardpane.html %}...{% include cardpane-end.html %}`

Template Language

Docsy uses Hugo’s Go templates, while Rustyll uses Liquid:

Docsy/Hugo	Rustyll
`{{ .Title }}`	`{{ page.title }}`
`{{ range .Pages }}`	`{% for page in site.pages %}`
`{{ end }}`	`{% endfor %}`
`{{ with .Site.Params.ui.feedback }}`	`{% if site.ui.feedback %}`…`{% endif %}`
`{{ partial "navbar.html" . }}`	`{% include navbar.html %}`

Front Matter Differences

# Docsy/Hugo
+++
title = "Getting Started"
weight = 1
description = "Getting started with Docsy"
+++

# Rustyll
---
title: Getting Started
weight: 1
description: Getting started with Rustyll
---

Configuration Conversion

Docsy’s configuration converts to Rustyll YAML:

# Docsy/Hugo (config.toml)
baseURL = "https://example.org/"
title = "My Documentation"

[params]
copyright = "The Authors"
github_repo = "https://github.com/me/myrepo"

[params.ui]
sidebar_menu_compact = true
breadcrumb_disable = false

Converts to:

# Rustyll (_config.yml)
url: "https://example.org"
title: "My Documentation"
copyright: "The Authors"
github_repo: "https://github.com/me/myrepo"
ui:
  sidebar_menu_compact: true
  breadcrumb_disable: false

Documentation Structure

Docsy’s documentation structure with sections and subsections maps to Rustyll’s collections:

# Rustyll collection configuration
collections:
  docs:
    output: true
    permalink: /docs/:path/
    order:
      - getting-started.md
      - concepts.md
      - tutorials.md
  
  tutorials:
    output: true
    permalink: /tutorials/:path/

Docsy’s sidebar navigation can be recreated in Rustyll:

# _data/navigation.yml
docs:
  - title: Getting Started
    url: /docs/getting-started/
    children:
      - title: Installation
        url: /docs/installation/
      - title: Configuration
        url: /docs/configuration/
  
  - title: Concepts
    url: /docs/concepts/

Search Implementation

Rustyll provides search capabilities for documentation sites:

# _config.yml
search:
  enabled: true
  provider: lunr # Fast search engine
  index_fields:
    - title
    - content
    - tags
    - categories

Landing Page

Docsy landing pages use blocks/sections which convert to Rustyll includes:

<!-- Rustyll landing page -->

{% include hero.html 
  title="My Documentation"
  description="Comprehensive guides for my project"
  button_text="Get Started"
  button_url="/docs/getting-started/"
%}

{% include feature-grid.html %}

Performance Optimization

Rustyll offers superior performance compared to Hugo/Docsy:

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

Troubleshooting Common Issues

Complex Docsy Components

Some complex Docsy components may require manual attention:

Check complex shortcodes like swaggerui or custom components
Review JavaScript interactions that may need adaptation
Verify that automatically created includes work as expected

Multi-language Support

If your Docsy site uses multiple languages:

Configure Rustyll’s language settings
Set up language-specific collections
Create language switcher include