Migrating from Harp

Migrating from Node.js-based Harp to Rustyll? This guide will help you transition your site to high-performance Rust-powered Rustyll while preserving your content structure and preprocessing capabilities.

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

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

This command will:

Copy all content files
Convert Harp’s metadata (_data.json) to Rustyll front matter
Transform Jade/Pug templates to Liquid templates
Process EJS templates to Liquid format
Generate a migration report

Directory Structure Differences

Harp	Rustyll	Notes
Root directory	Root directory	Content files stay in same location
`_layout.jade/ejs`	`_layouts/default.html`	Layout templates
`_partials/`	`_includes/`	Partial templates
`_data.json`	Front matter in files	Metadata moves into individual files
Public folder (if used)	Root directory	Content is unified
`harp.json`	`_config.yml`	Configuration file
`www/`	`_site/`	Generated site

Content Conversion

Harp content files with metadata in _data.json convert to Rustyll’s front matter:

// Harp (_data.json)
{
  "about": {
    "title": "About Us",
    "layout": "_layout"
  }
}

//- Harp (about.jade)
h1= title
p This is the about page.

Converts to:

---
title: About Us
layout: default
---

# Migrating from Harp
This is the about page.

Template Conversion

Jade/Pug to Liquid

Harp’s Jade/Pug templates convert to Liquid:

//- Harp (_layout.jade)
doctype html
html
  head
    title= title
    link(rel="stylesheet", href="/css/style.css")
  body
    header
      include _partials/nav
    main
      != yield
    footer
      p &copy; #{new Date().getFullYear()} My Company

Converts to:

<!-- Rustyll (_layouts/default.html) -->
<!DOCTYPE html>
<html>
  <head>
    <title>{{ page.title }}</title>
    <link rel="stylesheet" href="{{ '/css/style.css' | relative_url }}">
  </head>
  <body>
    <header>
      `{% include nav.html %}`
    </header>
    <main>
      {{ content }}
    </main>
    <footer>
      <p>&copy; {{ 'now' | date: "%Y" }} My Company</p>
    </footer>
  </body>
</html>

EJS to Liquid

Harp’s EJS templates convert to Liquid:

<!-- Harp (_layout.ejs) -->
<!DOCTYPE html>
<html>
  <head>
    <title><%= title %></title>
    <link rel="stylesheet" href="/css/style.css">
  </head>
  <body>
    <header>
      <%- partial("_partials/nav") %>
    </header>
    <main>
      <%- yield %>
    </main>
    <footer>
      <p>&copy; <%= new Date().getFullYear() %> My Company</p>
    </footer>
  </body>
</html>

Converts to the same Liquid template shown above.

Preprocessing Conversion

Harp’s built-in preprocessors have Rustyll equivalents:

Harp	Rustyll	Notes
Jade/Pug	Liquid	Template language
EJS	Liquid	Template language
Markdown	Markdown	Content format (same)
LESS	SCSS	CSS preprocessor
Stylus	SCSS	CSS preprocessor
CoffeeScript	JavaScript	JS preprocessor (manual conversion)

Configuration Conversion

Harp’s JSON configuration converts to Rustyll’s YAML:

// Harp (harp.json)
{
  "globals": {
    "site_name": "My Harp Site",
    "site_description": "A site built with Harp",
    "author": "Your Name"
  }
}

Converts to:

# Rustyll (_config.yml)
title: My Harp Site
description: A site built with Harp
author: Your Name

# Default settings for Markdown processing
markdown: kramdown

# Sass configuration
sass:
  style: compressed

Metadata Files

Harp’s metadata files (_data.json) are split into front matter for individual files in Rustyll. Collection data can be placed in _data/ files:

// Harp (projects/_data.json)
{
  "project1": {
    "title": "First Project",
    "description": "Description of first project",
    "featured": true
  },
  "project2": {
    "title": "Second Project",
    "description": "Description of second project",
    "featured": false
  }
}

Converts to:

# Rustyll (_data/projects.yml)
- slug: project1
  title: First Project
  description: Description of first project
  featured: true
- slug: project2
  title: Second Project
  description: Description of second project
  featured: false

URL Structure

Harp’s automatic index.html and clean URLs are supported in Rustyll:

# Rustyll (_config.yml)
permalink: pretty  # Generates URLs without .html extension

Asset Pipeline

Harp’s asset preprocessing converts to Rustyll’s asset handling:

Harp	Rustyll	Notes
LESS/Stylus	SCSS	CSS preprocessing
CoffeeScript	JavaScript	Manual conversion needed
Asset fingerprinting	Built-in asset hashing	File fingerprinting

Dynamic Content

Harp’s approach to handling collections converts to Rustyll collections:

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

With corresponding front matter in collection files:

# Rustyll (_projects/project1.md)
---
title: First Project
description: Description of first project
featured: true
---

Content for first project goes here.

Performance Improvements

Rustyll offers significant performance advantages over Node.js-based Harp:

# 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

Troubleshooting Common Issues

Template Language Differences

If you encounter template conversion issues:

Check for complex Jade/Pug or EJS constructs that need manual conversion
Replace JavaScript template logic with Liquid equivalents
Use includes for repeatable components

Missing Preprocessors

If you use preprocessors not directly supported in Rustyll:

Convert CoffeeScript to JavaScript manually
Transform Stylus to SCSS syntax
Use standard preprocessing tools before adding to the Rustyll site

Global Variables

Harp’s globals work differently in Rustyll:

Site-wide variables belong in _config.yml
Access them using ``
For complex data structures, use YAML data files

Rustyll