Migrate from 0.2
4 minutes read
0.2 built a site with Jekyll: a gem or remote_theme, _config.yml, Liquid, and _includes. 0.3 replaces that with the Mizzen engine and the Lateen theme, which run on Node. Your Markdown, most front matter, and the shape of _data/navigation.yml carry over; the Jekyll machinery and the Liquid that called it do not.
Before you start
- Commit the site or work on a copy. The migration tool writes files.
- Install Node 24.
- Keep the 0.2 site deployable while you migrate. A 0.2 repository can stay on
remote_theme: arminazimi/slipway@v0.2.0, or on thelegacy/jekyllbranch; neither gets new features.
1. Run the migration tool
Run it on the site folder, first as a dry run:
npx slipway migrate ../my-site --dry-run
npx slipway migrate ../my-site
From a checkout of this repository, before the migrate command is published, run the same tool directly:
node tools/migrate/run.ts ../my-site --dry-run
node tools/migrate/run.ts ../my-site
The report lists every file it changed, every file it removed, and every step left for a person. It does three things:
- Config. Converts
_config.ymlto the new config, keeps comments on keys that survive, and lists each dropped key with its reason. It removes_config.ymlonly after the new file is valid. - Content. Renames the front matter keys that changed and turns a standalone callout include into a
:::calloutdirective. Every other Liquid tag or output stays where it is and is reported with its file and line. - Navigation. Checks
_data/navigation.ymlagainst the engine's schema and reports problems with their line. It never rewrites navigation, because a URL such asdocs/xneeds a person's decision.
The tool writes slipway.yml, the name from before the engine and theme were renamed. Rename it once:
mv slipway.yml mizzen.yml
That is the only config file 0.3 reads.
2. Remove the Jekyll machinery
From the site root:
rm -rf _layouts _includes _plugins _site .jekyll-cache
rm -f Gemfile Gemfile.lock slipway-theme.gemspec .ruby-version _config.remote.yml
_data/navigation.yml stays: the engine reads the same shape. Remove copies of the old theme's CSS and JavaScript from assets/; keep the images and files the site owns.
3. Remove the files 0.3 generates
The 0.2 theme generated these files. 0.3 writes its own copy on every build, and a file in the site wins over a generated one silently, so a leftover would hide the new output:
find . -name '*.twin.html' -delete
rm -f search.json sitemap.xml llms.txt llms-full.txt sourcemap.json
Keep one only when you intend to own that path.
4. Replace what the old theme provided
Layouts
The theme ships base, doc, home, not-found, and versions. The migration tool renames page and default to doc; the others keep their names. Every other 0.2 layout (post, archive, author, tags, feed, adr, adr-index, changelog, changelog-feed, glossary, links, translation-status) is gone: rewrite the page with doc or without a layout. The 0.2 layouts that generated llms.txt, llms-full.txt, search.json, sitemap.xml, and sourcemap.json have no replacement page; remove those pages with step 3.
Liquid and blocks
The engine does not run Liquid. The tool converts the callout include; everything else it reports must become Markdown or a directive.
| 0.2 include | 0.3 |
|---|---|
blocks/callout.html |
:::callout{type="tip"} … ::: |
blocks/steps.html |
:::steps around an ordered list |
blocks/code-group.html |
:::code-tabs |
blocks/file-tree.html |
:::file-tree |
blocks/terminal.html |
:::terminal |
blocks/figure.html |
:::figure{src="…" alt="…"} |
blocks/embed.html |
::embed{src="…" title="…"} |
blocks/endpoint.html |
:::endpoint |
blocks/kbd.html |
:kbd[Ctrl+K] |
blocks/badge.html |
::badge{label="New"} |
The other 0.2 blocks have no one-line replacement. Rewrite them as Markdown or with a theme component, or delete them when they were marketing blocks that 0.3 does not ship.
The home page
The home layout reads hero, actions, and sections from front matter. The 0.2 cta_text, cta_url, and variant keys are gone; move the button into actions:
---
title: My docs
layout: home
hero:
eyebrow: Documentation
title: My docs
lead: Build the site, preview it, and publish it to GitHub Pages.
actions:
- label: Quickstart
url: /quickstart/
primary: true
sections:
- title: Guides
url: /guides/
description: Customize the site and migrate from 0.2.
links:
- title: Install
url: /install/
---
Overrides
_includes/head-custom.html, _includes/footer-custom.html, assets/css/custom.css, and assets/images/social.png are not read in 0.3. Remove them. Put anything you still need in the page body or a theme component; the theme's customization guide covers the theme.options blocks it does read.
Config and theme options
A slipway: group dissolves. languages and search move to the top level; header, fonts, logo, tokens, analytics, persian, and arabic move under theme.options; comments, social, tokens.font_display, persian.jalali, and arabic.hijri are dropped. The 0.3 theme reads announcement, logo, footer, pageAgent, and feedback; an option it does not read has no effect.
Other renames:
baseurlbecomesbase, with the same value: a leading/and no trailing slash.defaults[].scope.pathbecomesdefaults[].path;scope.typeis dropped because there are no collections.permalinkis dropped because the file path gives the URL. A page that needs another URL setspermalink, andredirectscovers the old one.themeandremote_themeare dropped when they namedslipway-themeorarminazimi/slipway, the theme that ships by default.pluginsare dropped. Optional front matter,README.mdindexes, redirects, the sitemap, and SEO tags are built in.
The configuration reference describes the new keys.
5. Build and deploy
npm install --save-dev @velella/mizzen @velella/lateen
npx mizzen check .
npx mizzen build . --out dist
check builds to a temporary folder and prints diagnostics. build writes dist; a build fails on an unknown layout, an unknown config key, or two files writing the same path. Set url in mizzen.yml to publish a sitemap and canonical links.
Classic GitHub Pages cannot build a 0.3 site because it ran Jekyll. Build on Node in a workflow, publish the output folder, and deploy it with the Pages actions; in the repository's Pages settings, the source is GitHub Actions, not a branch. The starter workflow is in Install and quickstart.
Staying on 0.2
A site that is not ready to move can stay on 0.2.0. Keep remote_theme: arminazimi/slipway@v0.2.0, or use the legacy/jekyll branch, which is the last Jekyll release. Neither gets new features, and neither can use the engine's docs layouts or the outputs it generates.