Migrating from Middleman

Migrating from Ruby-based Middleman to Rustyll? This guide will help you transition your site to high-performance Rust-powered Rustyll while preserving your content and maintaining a familiar development workflow.

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

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

This command will:

Copy all content files
Convert Middleman frontmatter to Rustyll format
Transform Middleman templates to Liquid templates
Adjust configuration settings
Generate a migration report

Directory Structure Differences

Middleman	Rustyll	Notes
`source/`	Root directory	Content goes in the root folder in Rustyll
`source/layouts/`	`_layouts/`	Layout templates
`source/partials/`	`_includes/`	Partial templates
`data/`	`_data/`	Data files
`config.rb`	`_config.yml`	Configuration file
`build/`	`_site/`	Generated site
`source/blog/`	`_posts/`	Blog articles

Content Conversion

Middleman pages convert to Rustyll pages:

<!-- Middleman (source/about.html.erb) -->
---
title: About Us
layout: page
---

<h1><%= current_page.data.title %></h1>
<p>This is the about page.</p>

Converts to:

<!-- Rustyll (about.md) -->
---
title: About Us
layout: page
---

# {{ page.title }}
This is the about page.

Blog Articles

Middleman blog articles convert to Rustyll posts:

<!-- Middleman (source/blog/2023-01-15-hello-world.html.md) -->
---
title: Hello World
date: 2023-01-15
tags: welcome, introduction
---

This is my first blog post.

Converts to:

<!-- Rustyll (_posts/2023-01-15-hello-world.md) -->
---
title: Hello World
date: 2023-01-15
tags:
  - welcome
  - introduction
---

This is my first blog post.

Configuration Conversion

Middleman’s Ruby configuration converts to Rustyll’s YAML:

# Middleman (config.rb)
set :site_title, "My Middleman Site"
set :site_url, "https://example.com"
set :markdown_engine, :kramdown
set :css_dir, 'stylesheets'
set :js_dir, 'javascripts'
set :images_dir, 'images'

activate :blog do |blog|
  blog.prefix = "blog"
  blog.permalink = "{year}/{month}/{day}/{title}.html"
  blog.layout = "blog_layout"
end

activate :livereload
activate :directory_indexes

Converts to:

# Rustyll (_config.yml)
title: "My Middleman Site"
url: "https://example.com"
markdown: kramdown
sass:
  sass_dir: _sass
  style: compressed

# Blog configuration
permalink: /:year/:month/:day/:title/
defaults:
  - scope:
      path: ""
      type: "posts"
    values:
      layout: "blog_layout"

# Live reload is built into Rustyll serve
livereload: true

Template Conversion

Middleman uses ERB, Haml, or other templates, while Rustyll uses Liquid:

Middleman (ERB)	Rustyll (Liquid)
`<%= current_page.data.title %>`	`{{ page.title }}`
`<% blog.articles.each do \|article\| %>`	`{% for post in site.posts %}`
`<% end %>`	`{% endfor %}`
`<%= partial "header" %>`	`{% include header.html %}`
`<%= yield %>`	`{{ content }}`
`<%= link_to "Home", "/" %>`	`<a href="{{ '/' \| relative_url }}">Home</a>`
`<%= asset_path :css, 'style' %>`	`{{ '/assets/css/style.css' \| relative_url }}`

Helper Functions

Middleman helpers convert to Liquid filters or includes:

Middleman Helper	Rustyll Equivalent
`link_to`	HTML links with `relative_url` filter
`image_tag`	HTML img tags with `relative_url` filter
`asset_path`	`relative_url` filter
`current_page.data.x`	`page.x`
Custom helpers	Liquid includes or custom plugins

Asset Pipeline

Middleman’s asset pipeline converts to Rustyll’s asset handling:

Middleman	Rustyll	Notes
Sprockets	Built-in Sass/Asset processing	Automatic compilation
Asset hashing	Built-in asset hashing	File fingerprinting
CSS import	Sass imports	Combining stylesheets
JS concatenation	JS includes	Combining scripts

Data Files

Middleman data files are fully compatible with Rustyll:

# Both systems (data/team.yml)
- name: John Doe
  position: Developer
  
- name: Jane Smith
  position: Designer

Used in Middleman as data.team and in Rustyll as site.data.team.

Front Matter Defaults

Middleman’s blog configuration options convert to Rustyll front matter defaults:

# Rustyll (_config.yml)
defaults:
  - scope:
      path: ""
      type: "posts"
    values:
      layout: "post"
      author: "Default Author"
  
  - scope:
      path: "projects"
    values:
      layout: "project"
      permalink: "/projects/:title/"

Extensions to Plugins

Middleman extensions convert to Rustyll plugins:

Middleman Extension	Rustyll Equivalent
`middleman-blog`	Built-in blog functionality
`middleman-livereload`	`--livereload` flag
`middleman-search`	`rustyll-search` plugin
`middleman-syntax`	Built-in syntax highlighting
`middleman-autoprefixer`	`rustyll-autoprefixer` plugin

Performance Improvements

Rustyll offers significant performance advantages over Ruby-based Middleman:

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

Benefits include:

Build Speed: 10-20x faster builds
Memory Usage: Significantly lower resource consumption
Live Reload: Faster refresh during development

Troubleshooting Common Issues

Ruby Dependencies

If your Middleman site relies on Ruby gems:

Look for Rustyll plugin equivalents
Consider alternative implementation strategies
Simplify functionality where appropriate

Template Engine Differences

If you use template engines other than ERB:

Convert Haml/Slim to HTML with Liquid tags
Replace complex template logic with simpler Liquid equivalents
Create includes for repeatable components

Custom Extensions

If you use custom Middleman extensions:

Review the functionality needed
Look for Rustyll plugins that provide similar features
Consider creating custom Rustyll plugins

Rustyll