Migrating from Jekyll

Migrating from Ruby-based Jekyll to Rustyll? This guide will help you transition to a high-performance Rust-powered static site generator while maintaining compatibility with your existing Jekyll site.

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 specifically designed for Jekyll sites:

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

This command will:

Copy all content files
Adapt Jekyll-specific Liquid tags to Rustyll’s syntax
Preserve front matter
Convert Ruby plugins to Rust equivalents when possible
Generate a detailed migration report

Directory Structure

The good news is that Rustyll maintains Jekyll’s directory structure, making migration fairly straightforward:

Jekyll	Rustyll	Notes
`_posts/`	`_posts/`	Blog posts (same structure)
`_layouts/`	`_layouts/`	Layout templates (same format)
`_includes/`	`_includes/`	Include files (same format)
`_data/`	`_data/`	Data files (same format)
`_config.yml`	`_config.yml`	Configuration (similar structure)
`_site/`	`_site/`	Generated site
`assets/`	`assets/`	Static assets (same structure)

Content Files

Jekyll posts and pages work almost identically in Rustyll:

---
layout: post
title: "My First Post"
date: 2023-04-15
categories: blog rust
---

This is my **first** blog post using Rustyll.

This format works without modification in Rustyll.

Template System

Both Jekyll and Rustyll use Liquid templates, with some differences:

Jekyll (Liquid)	Rustyll (Liquid)	Notes
`{{ page.title }}`	`{{ page.title }}`	Same syntax
`{% include header.html %}`	`{% include header.html %}`	Same syntax
`{% link index.md %}`	`{{ '/index' \| relative_url }}`	URL generation differences
`{% post_url 2023-04-15-first-post %}`	`{{ '/blog/2023/04/15/first-post' \| relative_url }}`	Post URL differences
`{{ site.github.contributors }}`	N/A	GitHub-specific variables not available

Configuration File

Jekyll’s _config.yml converts to Rustyll’s format with some changes:

# Jekyll (_config.yml)
title: My Jekyll Site
description: A site built with Jekyll
url: https://example.com
baseurl: /my-site
markdown: kramdown
permalink: /blog/:year/:month/:day/:title/
plugins:
  - jekyll-feed
  - jekyll-seo-tag
sass:
  style: compressed

Converts to:

# Rustyll (_config.yml)
title: My Jekyll Site
description: A site built with Jekyll
url: https://example.com
base_url: /my-site
markdown: commonmark
permalink: /blog/:year/:month/:day/:title/
plugins:
  - rustyll-feed
  - rustyll-seo
sass:
  style: compressed
threads: auto  # Rustyll-specific option

Collections

Jekyll collections convert easily to Rustyll:

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

Converts to:

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

Front Matter Defaults

Jekyll’s front matter defaults work similarly in Rustyll:

# Jekyll (_config.yml)
defaults:
  - scope:
      path: ""
      type: "posts"
    values:
      layout: "post"
      author: "John Doe"

Converts to the same format in Rustyll.

Plugin System

Jekyll plugins need to be replaced with Rustyll equivalents:

Jekyll Plugin	Rustyll Plugin	Notes
`jekyll-feed`	`rustyll-feed`	RSS/Atom feed generation
`jekyll-seo-tag`	`rustyll-seo`	SEO meta tags
`jekyll-sitemap`	`rustyll-sitemap`	Sitemap generation
`jekyll-paginate`	Built-in pagination	Native pagination in Rustyll
Custom Ruby plugins	Rust plugins/hooks	Need manual conversion

Asset Pipeline

Jekyll’s asset handling converts to Rustyll’s system:

Jekyll	Rustyll	Notes
Sass/SCSS	Built-in Sass	Similar functionality
`jekyll-assets`	Asset pipeline	Similar functionality
Webpack integration	Webpack support	Similar approach

Performance Improvements

Rustyll offers significant performance advantages over Ruby-based Jekyll:

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

Benchmark comparisons:

Build Speed: 50-100x faster for large sites
Memory Usage: 80-90% less RAM consumption
Concurrency: Efficient parallelism with all CPU cores

Common Migration Challenges

Liquid Tags

Jekyll-specific Liquid tags need adjustment:

<!-- Jekyll -->

{% link about.md %}
{% post_url 2023-04-15-first-post %}

Converts to:

<!-- Rustyll -->

{{ '/about' | relative_url }}
{{ '/blog/2023/04/15/first-post' | relative_url }}

Custom Plugins

Ruby plugins need to be replaced with Rust equivalents:

Hooks: Use Rustyll’s hook system
Generators: Convert to Rustyll generators
Converters: Use Rustyll’s conversion system
Tags: Implement as Liquid filters or tags

GitHub Pages Integration

If you’re using GitHub Pages with Jekyll:

Setup GitHub Actions for Rustyll builds
Configure with the Rustyll GitHub action
Deploy to GitHub Pages from the built _site directory

Migration Checklist

Troubleshooting

Common Issues

Template Errors: Check for Jekyll-specific Liquid syntax
Missing Plugins: Install Rustyll plugin alternatives
URL Generation: Verify permalink settings match
Markdown Processing: Adjust for CommonMark vs Kramdown differences
Front Matter: Ensure proper handling of custom variables

Performance Tuning

For optimal performance:

Enable multi-threading
Configure aggressive caching
Use incremental builds during development

Rustyll