Migrating from MkDocs

Migrating from Python-based MkDocs to Rustyll? This guide will help you transition your documentation site while preserving content and structure, all with Rustyll’s superior performance.

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

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

This command will:

Copy all documentation files
Convert MkDocs-specific front matter to Rustyll format
Transform MkDocs theme templates to Liquid templates
Convert mkdocs.yml to Rustyll’s _config.yml
Generate a migration report

Directory Structure Differences

MkDocs	Rustyll	Notes
`docs/`	Root directory	Content goes in the root folder in Rustyll
`mkdocs.yml`	`_config.yml`	Configuration file (YAML format)
Custom theme in `theme/`	`_layouts/` and `_includes/`	Theme customizations
`docs/assets/`	`assets/`	Static assets

Configuration Conversion

MkDocs YAML configuration converts to Rustyll format:

# MkDocs (mkdocs.yml)
site_name: My Documentation
site_url: https://example.com
repo_url: https://github.com/me/myproject
theme: material

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - User Guide:
    - Installation: guide/installation.md
    - Configuration: guide/configuration.md

Converts to:

# Rustyll (_config.yml)
title: My Documentation
url: https://example.com
repository: https://github.com/me/myproject
theme: docs-material

# Navigation structure

The navigation structure is converted to:

# _data/navigation.yml
docs:
  - title: Home
    url: /
  - title: Getting Started
    url: /getting-started/
  - title: User Guide
    children:
      - title: Installation
        url: /guide/installation/
      - title: Configuration
        url: /guide/configuration/

Theme Conversion

MkDocs themes are converted to Rustyll themes:

MkDocs Theme	Rustyll Equivalent
Material	rustyll-docs-material
ReadTheDocs	rustyll-docs-readthedocs
MkDocs (default)	rustyll-docs-default
Custom	Converted to Liquid templates

Front Matter Differences

MkDocs pages typically have minimal front matter, but Rustyll may add more:

# MkDocs (often minimal/none)
---
title: Getting Started
---

# Rustyll
---
title: Getting Started
permalink: /getting-started/
layout: docs
---

Markdown Extensions

MkDocs markdown extensions have Rustyll equivalents:

MkDocs Extension	Rustyll Equivalent
Admonitions	Alert includes
CodeHilite	Syntax highlighting
TOC	Table of contents tag
Footnotes	Markdown footnotes
Metadata	Front matter

Admonition Conversion

MkDocs-style admonitions are converted to Rustyll includes:

# MkDocs
!!! note "Note Title"
    This is a note

# Rustyll
`{% include note.html title="Note Title" content="This is a note" %}`

Features and Plugins

Popular MkDocs plugins have Rustyll equivalents:

MkDocs Plugin	Rustyll Equivalent
Search	Built-in search
MathJax	rustyll-mathjax
PDF Export	rustyll-pdf
Redirects	rustyll-redirect-from
Social	rustyll-social
Git revision date	rustyll-git-metadata

Material Theme Features

If you’re using MkDocs Material theme, Rustyll provides equivalent features:

Material Feature	Rustyll Equivalent
Dark mode	Theme with dark mode
Search highlighting	Built-in search with highlighting
Content tabs	Tabs include
Annotations	Margin notes
Icons	SVG icons library

Performance Improvements

Rustyll offers significant performance advantages over Python-based MkDocs:

Build Speed: 10-20x faster builds
Memory Usage: Significantly lower resource consumption
Parallelism: Utilizes all CPU cores efficiently
Incremental Builds: Only rebuilds changed files

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

MkDocs navigation is explicitly defined in mkdocs.yml. In Rustyll, you have options:

Data file: Define navigation in _data/navigation.yml
Automatic: Generate from front matter and collection structure
Hybrid: Combine automatic with manual ordering

Search Implementation

MkDocs search is replaced with Rustyll’s search system:

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

Troubleshooting Common Issues

Python Extensions

If you rely on Python-specific plugins or extensions:

Look for Rustyll equivalents in the plugin ecosystem
Consider creating custom includes for unique functionality
Use the preprocessing phase of migration for complex conversions

Theme Customization

For heavily customized MkDocs themes:

Review the converted theme files
Adjust Liquid templates as needed
Update SCSS/CSS in the _sass directory