Migrating from Nanoc

Migrating from Ruby-based Nanoc to Rustyll? This guide will help you transition your site to high-performance Rust-powered Rustyll while preserving your content structure and customizations.

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

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

This command will:

Copy all content files
Convert Nanoc-specific front matter to Rustyll format
Transform Nanoc layouts to Rustyll templates
Convert Rules to appropriate configurations
Generate a migration report

Directory Structure Differences

Nanoc	Rustyll	Notes
`content/`	Root directory	Content goes in the root folder in Rustyll
`layouts/`	`_layouts/`	Layout templates
`lib/`	`_plugins/`	Custom helpers and functions
`Rules`	`_config.yml`	Compilation and routing rules
`nanoc.yaml`	`_config.yml`	Configuration settings
`output/`	`_site/`	Generated site

Content Conversion

Nanoc items convert to Rustyll pages or posts:

# Nanoc (content/articles/example.md)
---
title: Example Article
created_at: 2023-01-15
kind: article
tags:
  - example
  - tutorial
---

Content goes here.

Converts to:

# Rustyll (_posts/2023-01-15-example-article.md or regular page)
---
title: Example Article
date: 2023-01-15
layout: article
tags:
  - example
  - tutorial
---

Content goes here.

Rules Conversion

Nanoc’s Rules file defines compilation and routing, which convert to Rustyll configuration:

# Nanoc (Rules)
compile '/articles/**/*' do
  filter :kramdown
  layout '/article.*'
end

route '/articles/**/*' do
  y, m, d, slug = item.identifier.to_s.match(%r{/articles/(\d+)-(\d+)-(\d+)-([^/]+)}).captures
  "/blog/#{y}/#{m}/#{d}/#{slug}/index.html"
end

Converts to:

# Rustyll (_config.yml)
collections:
  posts:
    output: true
    permalink: /blog/:year/:month/:day/:title/

# Defaults for post processing
defaults:
  - scope:
      path: ""
      type: "posts"
    values:
      layout: "article"
      
markdown: kramdown

Configuration Conversion

Nanoc’s YAML configuration converts to Rustyll format:

# Nanoc (nanoc.yaml)
base_url: https://example.com
title: My Nanoc Site
author_name: Your Name
author_email: [email protected]

deploy:
  default:
    kind: rsync
    dst: "[email protected]:/var/www/mysite"

Converts to:

# Rustyll (_config.yml)
url: https://example.com
title: My Nanoc Site
author:
  name: Your Name
  email: [email protected]

Filters to Plugins

Nanoc’s custom filters can be converted to Rustyll plugins:

Nanoc Filter	Rustyll Equivalent
`filter :kramdown`	`markdown: kramdown`
`filter :erb`	Liquid templates
`filter :colorize_syntax`	Built-in syntax highlighting
`filter :sass`	Built-in Sass/SCSS processing
Custom filters	Custom Rust plugins

Helpers Conversion

Nanoc helpers convert to Liquid filters or tags in Rustyll:

Nanoc Helper	Rustyll Equivalent
`link_to(text, path)`	`[text](`{% link path %}`)`
`item[:attribute]`	`{{ page.attribute }}`
`@items['/path/*']`	`{% for page in site.pages %}`
Custom helpers	Liquid includes or custom plugins

Template Conversion

Nanoc templates (typically ERB) convert to Liquid templates:

Nanoc (ERB)	Rustyll (Liquid)
`<%= item[:title] %>`	`{{ page.title }}`
`<% items.each do \|i\| %>`	`{% for page in site.pages %}`
`<% end %>`	`{% endfor %}`
`<%= render '/partials/header.*' %>`	`{% include header.html %}`
`<%= item.compiled_content %>`	`{{ content }}`

Custom Data

Nanoc data files convert to Rustyll data files:

# Nanoc (content/data/members.yaml)
- name: John Doe
  role: Developer
  
- name: Jane Smith
  role: Designer

Converts to:

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

Used in templates as ``.

Blogging Features

Nanoc’s blogging features convert to Rustyll’s blogging system:

Nanoc	Rustyll	Notes
Article items	Posts	Date-based filename convention
Custom article sorting	Front matter with `date` field	Automatic date-based sorting
Tag pages	Collections for tags	Generated tag pages
Articles listing	Site-wide post variable	`site.posts`

Performance Improvements

Rustyll offers significant performance advantages over Ruby-based Nanoc:

# 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
Parallelism: Utilizes all CPU cores efficiently

Asset Pipeline

Nanoc’s asset processing converts to Rustyll’s asset system:

Nanoc	Rustyll	Notes
`filter :sass`	Built-in SASS processing	Automatic compilation
`filter :uglify_js`	Asset plugins	JS minification
Asset concatenation	Asset includes	Combined files
Custom asset filters	Custom plugins	Extended functionality

Troubleshooting Common Issues

Ruby Dependencies

If your Nanoc site relies on Ruby gems:

Look for Rustyll plugin equivalents
Consider using preprocessing during migration
Simplify dependencies where possible

Custom Rules

If you have complex compilation or routing rules:

Review permalink structures in _config.yml
Configure collections to match your routing needs
Use front matter defaults for consistent processing

Filter Chains

If you use complex filter chains in Nanoc:

Break down complex filters into simpler steps
Use Rustyll’s plugin ecosystem for specialized processing
Consider custom plugins for unique requirements

Rustyll