Migrating from Ruby-based Bridgetown to Rustyll? This guide will help you transition from Bridgetown’s modern Ruby architecture to Rustyll’s high-performance Rust-powered framework while preserving your content and components.
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 Bridgetown sites:
rustyll migrate --from bridgetown --source ./my-bridgetown-site --destination ./my-rustyll-site
This command will:
- Copy all content files
- Convert Bridgetown’s front matter to Rustyll format
- Transform Bridgetown’s Liquid/ERB templates to Rustyll’s Liquid templates
- Adjust configuration settings
- Generate a migration report
Directory Structure Differences
| Bridgetown | Rustyll | Notes |
|---|---|---|
src/ |
Root directory | Content files move to root folder in Rustyll |
src/_posts/ |
_posts/ |
Blog posts |
src/_pages/ |
Root directory | Static pages |
src/_layouts/ |
_layouts/ |
Layout templates |
src/_components/ |
_includes/ |
Component templates |
src/_data/ |
_data/ |
Data files |
bridgetown.config.yml |
_config.yml |
Configuration file |
frontend/ |
assets/ |
Frontend assets |
output/ |
_site/ |
Generated site |
Content Conversion
Pages
Bridgetown pages convert to Rustyll pages:
# Bridgetown (src/_pages/about.md)
---
layout: page
title: About Us
permalink: /about/
---
This is the about page content.
Converts to:
# Rustyll (about.md)
---
layout: page
title: About Us
permalink: /about/
---
This is the about page content.
Posts
Bridgetown posts convert to Rustyll posts:
# Bridgetown (src/_posts/2023-01-15-hello-world.md)
---
layout: post
title: Hello World
date: 2023-01-15 12:00:00 -0500
categories:
- announcements
---
This is my first blog post.
Converts to:
# Rustyll (_posts/2023-01-15-hello-world.md)
---
layout: post
title: Hello World
date: 2023-01-15 12:00:00 -0500
categories:
- announcements
---
This is my first blog post.
Configuration Conversion
Bridgetown’s YAML configuration converts to Rustyll’s format:
# Bridgetown (bridgetown.config.yml)
url: https://example.com
title: My Bridgetown Site
timezone: America/New_York
permalink: pretty
template_engine: liquid
pagination:
enabled: true
per_page: 10
collections:
projects:
output: true
permalink: /projects/:slug/
Converts to:
# Rustyll (_config.yml)
url: https://example.com
title: My Bridgetown Site
timezone: America/New_York
permalink: pretty
# Pagination
paginate: 10
paginate_path: "/page:num/"
# Collections
collections:
projects:
output: true
permalink: /projects/:slug/
Template Conversion
Liquid Templates
Bridgetown Liquid templates are compatible with Rustyll with minor changes:
| Bridgetown (Liquid) | Rustyll (Liquid) |
|---|---|
| Page title variable | Same page title variable |
| Loop through collection resources | Loop through site posts |
| Render component with parameters | Include partial with parameters |
| Data access with square brackets | Same data access pattern |
Components
Bridgetown components convert to Rustyll includes:
# Bridgetown (src/_components/shared/card.liquid)
<div class="card">
<h3><!-- --></h3>
<div class="content">
<!-- <section class="docs-shell container"><div class="docs-mobile-nav"><details class="mobile-docs"><summary>Browse documentation <span aria-hidden="true">⌄</span></summary><div class="mobile-docs-content"><nav class="docs-links" aria-label="Documentation sections"><h2>Getting Started</h2><ul><li><a href="/docs/" >Quickstart</a></li><li><a href="/docs/installation/" >Installation</a></li><li><a href="/docs/rust-101/" >Rust 101 for Rustyll Users</a></li><li><a href="/docs/community/" >Community</a></li><li><a href="/docs/step-by-step/01-setup/" >Step by Step Tutorial</a></li></ul><h2>Build</h2><ul><li><a href="/docs/usage/" >Command Line Usage</a></li><li><a href="/docs/configuration/" >Configuration</a></li><li><a href="/docs/rendering-process/" >Rendering Process</a></li></ul><h2>Content</h2><ul><li><a href="/docs/pages/" >Pages</a></li><li><a href="/docs/posts/" >Posts</a></li><li><a href="/docs/front-matter/" >Front Matter</a></li><li><a href="/docs/collections/" >Collections</a></li><li><a href="/docs/datafiles/" >Data Files</a></li><li><a href="/docs/assets/" >Assets</a></li><li><a href="/docs/static-files/" >Static Files</a></li></ul><h2>Site Structure</h2><ul><li><a href="/docs/structure/" >Directory Structure</a></li><li><a href="/docs/liquid/" >Liquid</a></li><li><a href="/docs/variables/" >Variables</a></li><li><a href="/docs/includes/" >Includes</a></li><li><a href="/docs/layouts/" >Layouts</a></li><li><a href="/docs/permalinks/" >Permalinks</a></li><li><a href="/docs/themes/" >Themes</a></li><li><a href="/docs/pagination/" >Pagination</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/plugins/" >Plugins</a></li><li><a href="/docs/migrations/" >Blog Migrations</a></li><li><a href="/docs/upgrading/" >Upgrading</a></li><li><a href="/docs/deployment/" >Deployment</a></li></ul><h2>Migrating</h2><ul><li><a href="/docs/migrating/" >Migrating to Rustyll</a></li><li><a href="/docs/migrating/assemble-to-rustyll/" aria-current="page">Migrating from Assemble</a></li><li><a href="/docs/migrating/bridgetown-to-rustyll/" >Migrating from Bridgetown</a></li><li><a href="/docs/migrating/cobalt-to-rustyll/" >Migrating from Cobalt</a></li><li><a href="/docs/migrating/docsy-to-rustyll/" >Migrating from Docsy</a></li><li><a href="/docs/migrating/eleventy-to-rustyll/" >Migrating from Eleventy</a></li><li><a href="/docs/migrating/fresh-to-rustyll/" >Migrating from Fresh</a></li><li><a href="/docs/migrating/gatsby-to-rustyll/" >Migrating from Gatsby</a></li><li><a href="/docs/migrating/gitbook-to-rustyll/" >Migrating from GitBook</a></li><li><a href="/docs/migrating/harp-to-rustyll/" >Migrating from Harp</a></li><li><a href="/docs/migrating/hugo-to-rustyll/" >Migrating from Hugo</a></li><li><a href="/docs/migrating/jekyll-to-rustyll/" >Migrating from Jekyll</a></li><li><a href="/docs/migrating/mdbook-to-rustyll/" >Migrating from mdBook</a></li><li><a href="/docs/migrating/middleman-to-rustyll/" >Migrating from Middleman</a></li><li><a href="/docs/migrating/mkdocs-to-rustyll/" >Migrating from MkDocs</a></li><li><a href="/docs/migrating/nanoc-to-rustyll/" >Migrating from Nanoc</a></li><li><a href="/docs/migrating/pelican-to-rustyll/" >Migrating from Pelican</a></li><li><a href="/docs/migrating/slate-to-rustyll/" >Migrating from Slate</a></li><li><a href="/docs/migrating/zola-to-rustyll/" >Migrating from Zola</a></li></ul></nav>
</div></details>
</div><div class="docs-grid"><aside class="docs-sidebar"><div class="docs-sidebar-inner"><a class="search-trigger" href="/search/" data-search-open>Search documentation <span aria-hidden="true">⌕</span></a><nav class="docs-links" aria-label="Documentation sections"><h2>Getting Started</h2><ul><li><a href="/docs/" >Quickstart</a></li><li><a href="/docs/installation/" >Installation</a></li><li><a href="/docs/rust-101/" >Rust 101 for Rustyll Users</a></li><li><a href="/docs/community/" >Community</a></li><li><a href="/docs/step-by-step/01-setup/" >Step by Step Tutorial</a></li></ul><h2>Build</h2><ul><li><a href="/docs/usage/" >Command Line Usage</a></li><li><a href="/docs/configuration/" >Configuration</a></li><li><a href="/docs/rendering-process/" >Rendering Process</a></li></ul><h2>Content</h2><ul><li><a href="/docs/pages/" >Pages</a></li><li><a href="/docs/posts/" >Posts</a></li><li><a href="/docs/front-matter/" >Front Matter</a></li><li><a href="/docs/collections/" >Collections</a></li><li><a href="/docs/datafiles/" >Data Files</a></li><li><a href="/docs/assets/" >Assets</a></li><li><a href="/docs/static-files/" >Static Files</a></li></ul><h2>Site Structure</h2><ul><li><a href="/docs/structure/" >Directory Structure</a></li><li><a href="/docs/liquid/" >Liquid</a></li><li><a href="/docs/variables/" >Variables</a></li><li><a href="/docs/includes/" >Includes</a></li><li><a href="/docs/layouts/" >Layouts</a></li><li><a href="/docs/permalinks/" >Permalinks</a></li><li><a href="/docs/themes/" >Themes</a></li><li><a href="/docs/pagination/" >Pagination</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/plugins/" >Plugins</a></li><li><a href="/docs/migrations/" >Blog Migrations</a></li><li><a href="/docs/upgrading/" >Upgrading</a></li><li><a href="/docs/deployment/" >Deployment</a></li></ul><h2>Migrating</h2><ul><li><a href="/docs/migrating/" >Migrating to Rustyll</a></li><li><a href="/docs/migrating/assemble-to-rustyll/" aria-current="page">Migrating from Assemble</a></li><li><a href="/docs/migrating/bridgetown-to-rustyll/" >Migrating from Bridgetown</a></li><li><a href="/docs/migrating/cobalt-to-rustyll/" >Migrating from Cobalt</a></li><li><a href="/docs/migrating/docsy-to-rustyll/" >Migrating from Docsy</a></li><li><a href="/docs/migrating/eleventy-to-rustyll/" >Migrating from Eleventy</a></li><li><a href="/docs/migrating/fresh-to-rustyll/" >Migrating from Fresh</a></li><li><a href="/docs/migrating/gatsby-to-rustyll/" >Migrating from Gatsby</a></li><li><a href="/docs/migrating/gitbook-to-rustyll/" >Migrating from GitBook</a></li><li><a href="/docs/migrating/harp-to-rustyll/" >Migrating from Harp</a></li><li><a href="/docs/migrating/hugo-to-rustyll/" >Migrating from Hugo</a></li><li><a href="/docs/migrating/jekyll-to-rustyll/" >Migrating from Jekyll</a></li><li><a href="/docs/migrating/mdbook-to-rustyll/" >Migrating from mdBook</a></li><li><a href="/docs/migrating/middleman-to-rustyll/" >Migrating from Middleman</a></li><li><a href="/docs/migrating/mkdocs-to-rustyll/" >Migrating from MkDocs</a></li><li><a href="/docs/migrating/nanoc-to-rustyll/" >Migrating from Nanoc</a></li><li><a href="/docs/migrating/pelican-to-rustyll/" >Migrating from Pelican</a></li><li><a href="/docs/migrating/slate-to-rustyll/" >Migrating from Slate</a></li><li><a href="/docs/migrating/zola-to-rustyll/" >Migrating from Zola</a></li></ul></nav>
</div>
</aside><div class="docs-main"><div class="doc-content"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/docs/">Documentation</a><span aria-hidden="true">/</span><span>Migrating from Assemble</span></nav><h1>Migrating from Assemble</h1><details class="mobile-page-toc"><summary>On this page</summary>
<nav class="page-toc " aria-label="On this page"><h2>On this page</h2><ul>
<li class="toc-level-2"><a href="#installation">Installation</a></li><li class="toc-level-2"><a href="#automatic-migration">Automatic Migration</a></li><li class="toc-level-2"><a href="#directory-structure-differences">Directory Structure Differences</a></li><li class="toc-level-2"><a href="#content-conversion">Content Conversion</a></li><li class="toc-level-2"><a href="#template-conversion">Template Conversion</a><ul><li class="toc-level-3"><a href="#handlebars-to-liquid">Handlebars to Liquid</a></li><li class="toc-level-3"><a href="#partials-to-includes">Partials to Includes</a></li></ul></li><li class="toc-level-2"><a href="#configuration-conversion">Configuration Conversion</a></li><li class="toc-level-2"><a href="#data-system-conversion">Data System Conversion</a></li><li class="toc-level-2"><a href="#helpers-to-filters-and-tags">Helpers to Filters and Tags</a></li><li class="toc-level-2"><a href="#collections">Collections</a></li><li class="toc-level-2"><a href="#performance-improvements">Performance Improvements</a></li><li class="toc-level-2"><a href="#troubleshooting-common-issues">Troubleshooting Common Issues</a><ul><li class="toc-level-3"><a href="#template-syntax-differences">Template Syntax Differences</a></li><li class="toc-level-3"><a href="#helper-functions">Helper Functions</a></li><li class="toc-level-3"><a href="#layout-system">Layout System</a></li></ul></li><li class="toc-level-2"><a href="#migration-checklist">Migration Checklist</a></li><li class="toc-level-2"><a href="#need-help">Need Help?</a></li>
</ul></nav>
</details><article class="prose prose-invert max-w-none"><p>Migrating from JavaScript-based Assemble to Rustyll? This guide will help you transition from Assemble’s component-based approach to Rustyll’s high-performance static site generation while preserving your content structure.</p>
<h2 id="installation">Installation</h2>
<p>First, install Rustyll using Cargo (Rust’s package manager):</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Install Rust if you haven't already</span>
curl <span class="nt">--proto</span> <span class="s1">'=https'</span> <span class="nt">--tlsv1</span>.2 <span class="nt">-sSf</span> https://sh.rustup.rs | sh
<span class="c"># Install Rustyll</span>
cargo <span class="nb">install </span>rustyll
</code></pre></div></div>
<h2 id="automatic-migration">Automatic Migration</h2>
<p>Rustyll provides a built-in migration tool for Assemble sites:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rustyll migrate <span class="nt">--from</span> assemble <span class="nt">--source</span> ./my-assemble-site <span class="nt">--destination</span> ./my-rustyll-site
</code></pre></div></div>
<p>This command will:</p>
<ol>
<li>Convert Assemble’s pages and templates to Rustyll format</li>
<li>Transform Handlebars templates to Liquid templates</li>
<li>Process YAML front matter</li>
<li>Adapt Assemble’s data organization to Rustyll’s approach</li>
<li>Generate a migration report</li>
</ol>
<h2 id="directory-structure-differences">Directory Structure Differences</h2>
<table>
<thead>
<tr>
<th>Assemble</th>
<th>Rustyll</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">pages/</code></td>
<td>Root directory</td>
<td>Content pages</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">templates/</code></td>
<td><code class="language-plaintext highlighter-rouge">_layouts/</code> and <code class="language-plaintext highlighter-rouge">_includes/</code></td>
<td>Templates are split by purpose</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">partials/</code></td>
<td><code class="language-plaintext highlighter-rouge">_includes/</code></td>
<td>Reusable components</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">data/</code></td>
<td><code class="language-plaintext highlighter-rouge">_data/</code></td>
<td>Data files (similar functionality)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">dist/</code></td>
<td><code class="language-plaintext highlighter-rouge">_site/</code></td>
<td>Generated site</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">assets/</code></td>
<td><code class="language-plaintext highlighter-rouge">assets/</code></td>
<td>Static assets (same structure)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">Gruntfile.js</code></td>
<td><code class="language-plaintext highlighter-rouge">_config.yml</code></td>
<td>Configuration</td>
</tr>
</tbody>
</table>
<h2 id="content-conversion">Content Conversion</h2>
<p>Assemble pages with YAML front matter convert to Rustyll’s format:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Assemble (pages/about.hbs) --></span>
---
title: About Us
layout: default
---
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"about"</span><span class="nt">></span>
<span class="nt"><h1></span>\{\{title\}\}<span class="nt"></h1></span>
<span class="nt"><p></span>This is the about page.<span class="nt"></p></span>
<span class="nt"></div></span>
</code></pre></div></div>
<p>Converts to:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Rustyll (about.html) --></span>
---
title: About Us
layout: default
---
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"about"</span><span class="nt">></span>
<span class="nt"><h1></span>Migrating from Assemble<span class="nt"></h1></span>
<span class="nt"><p></span>This is the about page.<span class="nt"></p></span>
<span class="nt"></div></span>
</code></pre></div></div>
<h2 id="template-conversion">Template Conversion</h2>
<h3 id="handlebars-to-liquid">Handlebars to Liquid</h3>
<p>Assemble’s Handlebars templates convert to Rustyll’s Liquid templates:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Assemble (templates/layouts/default.hbs) --></span>
<span class="cp"><!DOCTYPE html></span>
<span class="nt"><html></span>
<span class="nt"><head></span>
<span class="nt"><title></span>\{\{title\}\}<span class="nt"></title></span>
<span class="nt"><link</span> <span class="na">rel=</span><span class="s">"stylesheet"</span> <span class="na">href=</span><span class="s">"\{\{assets\}\}/css/style.css"</span><span class="nt">></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><header></span>
\{\{> header\}\}
<span class="nt"></header></span>
<span class="nt"><main></span>
\{\{> body\}\}
<span class="nt"></main></span>
<span class="nt"><footer></span>
\{\{> footer\}\}
<span class="nt"></footer></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</code></pre></div></div>
<p>Converts to:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Rustyll (_layouts/default.html) --></span>
<span class="cp"><!DOCTYPE html></span>
<span class="nt"><html></span>
<span class="nt"><head></span>
<span class="nt"><title></span><span class="c"><!-- Migrating from Assemble --></span><span class="nt"></title></span>
<span class="nt"><link</span> <span class="na">rel=</span><span class="s">"stylesheet"</span> <span class="na">href=</span><span class="s">"<!-- /assets/css/style.css -->"</span><span class="nt">></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><header></span>
<span class="c"><!-- <header class="site-header" id="site-header">
<div class="container header-inner">
<div class="header-brand">
<a href="/" class="brand " aria-label="Rustyll home"><img class="brand-original" src="/img/logo-2x.png" alt="Rustyll" width="113" height="55"></a>
<span class="header-family">BETTER WEB</span>
</div>
<nav class="desktop-nav" aria-label="Main navigation">
<a href="/" >Home</a><a href="/docs/" aria-current="page">Docs</a><a href="/resources/" >Resources</a><a href="/showcase/" >Showcase</a><a href="/news/" >News</a>
</nav>
<div class="header-actions">
<a href="/search/" class="search-trigger" data-search-open aria-label="Search documentation"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/></svg><span>Search</span><kbd>⌘ K</kbd></a>
<a class="header-github" href="https://github.com/betterwebinit/rustyll">GitHub <span aria-hidden="true">↗</span></a>
<a class="header-start" href="/docs/">Get started <span aria-hidden="true">→</span></a>
</div>
<button type="button" class="menu-toggle" id="mobile-menu-button" aria-label="Open navigation menu" aria-expanded="false" aria-controls="mobile-menu"><span>Menu</span><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 7h16M4 12h16M4 17h16"/></svg></button>
</div>
<nav id="mobile-menu" class="mobile-menu" aria-label="Mobile navigation" hidden><div class="container">
<a href="/" >Home</a><a href="/docs/" aria-current="page">Docs</a><a href="/resources/" >Resources</a><a href="/showcase/" >Showcase</a><a href="/news/" >News</a>
<a href="/search/" data-search-open>Search documentation</a>
<a href="https://github.com/betterwebinit/rustyll">GitHub ↗</a>
</div></nav>
<noscript><nav class="no-js-nav container" aria-label="Navigation"><a href="/">Home</a><a href="/docs/">Docs</a><a href="/resources/">Resources</a><a href="/showcase/">Showcase</a><a href="/news/">News</a></nav></noscript>
</header>
--></span>
<span class="nt"></header></span>
<span class="nt"><main></span>
<span class="c"><!-- <section class="docs-shell container"><div class="docs-mobile-nav"><details class="mobile-docs"><summary>Browse documentation <span aria-hidden="true">⌄</span></summary><div class="mobile-docs-content"><nav class="docs-links" aria-label="Documentation sections"><h2>Getting Started</h2><ul><li><a href="/docs/" >Quickstart</a></li><li><a href="/docs/installation/" >Installation</a></li><li><a href="/docs/rust-101/" >Rust 101 for Rustyll Users</a></li><li><a href="/docs/community/" >Community</a></li><li><a href="/docs/step-by-step/01-setup/" >Step by Step Tutorial</a></li></ul><h2>Build</h2><ul><li><a href="/docs/usage/" >Command Line Usage</a></li><li><a href="/docs/configuration/" >Configuration</a></li><li><a href="/docs/rendering-process/" >Rendering Process</a></li></ul><h2>Content</h2><ul><li><a href="/docs/pages/" >Pages</a></li><li><a href="/docs/posts/" >Posts</a></li><li><a href="/docs/front-matter/" >Front Matter</a></li><li><a href="/docs/collections/" >Collections</a></li><li><a href="/docs/datafiles/" >Data Files</a></li><li><a href="/docs/assets/" >Assets</a></li><li><a href="/docs/static-files/" >Static Files</a></li></ul><h2>Site Structure</h2><ul><li><a href="/docs/structure/" >Directory Structure</a></li><li><a href="/docs/liquid/" >Liquid</a></li><li><a href="/docs/variables/" >Variables</a></li><li><a href="/docs/includes/" >Includes</a></li><li><a href="/docs/layouts/" >Layouts</a></li><li><a href="/docs/permalinks/" >Permalinks</a></li><li><a href="/docs/themes/" >Themes</a></li><li><a href="/docs/pagination/" >Pagination</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/plugins/" >Plugins</a></li><li><a href="/docs/migrations/" >Blog Migrations</a></li><li><a href="/docs/upgrading/" >Upgrading</a></li><li><a href="/docs/deployment/" >Deployment</a></li></ul><h2>Migrating</h2><ul><li><a href="/docs/migrating/" >Migrating to Rustyll</a></li><li><a href="/docs/migrating/assemble-to-rustyll/" >Migrating from Assemble</a></li><li><a href="/docs/migrating/bridgetown-to-rustyll/" >Migrating from Bridgetown</a></li><li><a href="/docs/migrating/cobalt-to-rustyll/" >Migrating from Cobalt</a></li><li><a href="/docs/migrating/docsy-to-rustyll/" >Migrating from Docsy</a></li><li><a href="/docs/migrating/eleventy-to-rustyll/" >Migrating from Eleventy</a></li><li><a href="/docs/migrating/fresh-to-rustyll/" >Migrating from Fresh</a></li><li><a href="/docs/migrating/gatsby-to-rustyll/" >Migrating from Gatsby</a></li><li><a href="/docs/migrating/gitbook-to-rustyll/" >Migrating from GitBook</a></li><li><a href="/docs/migrating/harp-to-rustyll/" >Migrating from Harp</a></li><li><a href="/docs/migrating/hugo-to-rustyll/" >Migrating from Hugo</a></li><li><a href="/docs/migrating/jekyll-to-rustyll/" >Migrating from Jekyll</a></li><li><a href="/docs/migrating/mdbook-to-rustyll/" >Migrating from mdBook</a></li><li><a href="/docs/migrating/middleman-to-rustyll/" >Migrating from Middleman</a></li><li><a href="/docs/migrating/mkdocs-to-rustyll/" >Migrating from MkDocs</a></li><li><a href="/docs/migrating/nanoc-to-rustyll/" >Migrating from Nanoc</a></li><li><a href="/docs/migrating/pelican-to-rustyll/" >Migrating from Pelican</a></li><li><a href="/docs/migrating/slate-to-rustyll/" >Migrating from Slate</a></li><li><a href="/docs/migrating/zola-to-rustyll/" >Migrating from Zola</a></li></ul></nav>
</div></details>
</div><div class="docs-grid"><aside class="docs-sidebar"><div class="docs-sidebar-inner"><a class="search-trigger" href="/search/" data-search-open>Search documentation <span aria-hidden="true">⌕</span></a><nav class="docs-links" aria-label="Documentation sections"><h2>Getting Started</h2><ul><li><a href="/docs/" >Quickstart</a></li><li><a href="/docs/installation/" >Installation</a></li><li><a href="/docs/rust-101/" >Rust 101 for Rustyll Users</a></li><li><a href="/docs/community/" >Community</a></li><li><a href="/docs/step-by-step/01-setup/" >Step by Step Tutorial</a></li></ul><h2>Build</h2><ul><li><a href="/docs/usage/" >Command Line Usage</a></li><li><a href="/docs/configuration/" >Configuration</a></li><li><a href="/docs/rendering-process/" >Rendering Process</a></li></ul><h2>Content</h2><ul><li><a href="/docs/pages/" >Pages</a></li><li><a href="/docs/posts/" >Posts</a></li><li><a href="/docs/front-matter/" >Front Matter</a></li><li><a href="/docs/collections/" >Collections</a></li><li><a href="/docs/datafiles/" >Data Files</a></li><li><a href="/docs/assets/" >Assets</a></li><li><a href="/docs/static-files/" >Static Files</a></li></ul><h2>Site Structure</h2><ul><li><a href="/docs/structure/" >Directory Structure</a></li><li><a href="/docs/liquid/" >Liquid</a></li><li><a href="/docs/variables/" >Variables</a></li><li><a href="/docs/includes/" >Includes</a></li><li><a href="/docs/layouts/" >Layouts</a></li><li><a href="/docs/permalinks/" >Permalinks</a></li><li><a href="/docs/themes/" >Themes</a></li><li><a href="/docs/pagination/" >Pagination</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/plugins/" >Plugins</a></li><li><a href="/docs/migrations/" >Blog Migrations</a></li><li><a href="/docs/upgrading/" >Upgrading</a></li><li><a href="/docs/deployment/" >Deployment</a></li></ul><h2>Migrating</h2><ul><li><a href="/docs/migrating/" >Migrating to Rustyll</a></li><li><a href="/docs/migrating/assemble-to-rustyll/" >Migrating from Assemble</a></li><li><a href="/docs/migrating/bridgetown-to-rustyll/" >Migrating from Bridgetown</a></li><li><a href="/docs/migrating/cobalt-to-rustyll/" >Migrating from Cobalt</a></li><li><a href="/docs/migrating/docsy-to-rustyll/" >Migrating from Docsy</a></li><li><a href="/docs/migrating/eleventy-to-rustyll/" >Migrating from Eleventy</a></li><li><a href="/docs/migrating/fresh-to-rustyll/" >Migrating from Fresh</a></li><li><a href="/docs/migrating/gatsby-to-rustyll/" >Migrating from Gatsby</a></li><li><a href="/docs/migrating/gitbook-to-rustyll/" >Migrating from GitBook</a></li><li><a href="/docs/migrating/harp-to-rustyll/" >Migrating from Harp</a></li><li><a href="/docs/migrating/hugo-to-rustyll/" >Migrating from Hugo</a></li><li><a href="/docs/migrating/jekyll-to-rustyll/" >Migrating from Jekyll</a></li><li><a href="/docs/migrating/mdbook-to-rustyll/" >Migrating from mdBook</a></li><li><a href="/docs/migrating/middleman-to-rustyll/" >Migrating from Middleman</a></li><li><a href="/docs/migrating/mkdocs-to-rustyll/" >Migrating from MkDocs</a></li><li><a href="/docs/migrating/nanoc-to-rustyll/" >Migrating from Nanoc</a></li><li><a href="/docs/migrating/pelican-to-rustyll/" >Migrating from Pelican</a></li><li><a href="/docs/migrating/slate-to-rustyll/" >Migrating from Slate</a></li><li><a href="/docs/migrating/zola-to-rustyll/" >Migrating from Zola</a></li></ul></nav>
</div>
</aside><div class="docs-main"><div class="doc-content"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/docs/">Documentation</a><span aria-hidden="true">/</span><span>Markdown 101</span></nav><h1>Markdown 101</h1><details class="mobile-page-toc"><summary>On this page</summary>
<nav class="page-toc " aria-label="On this page"><h2>On this page</h2><ul>
<li class="toc-level-2"><a href="#basic-markdown-syntax">Basic Markdown Syntax</a><ul><li class="toc-level-3"><a href="#headers">Headers</a></li><li class="toc-level-3"><a href="#emphasis">Emphasis</a></li><li class="toc-level-3"><a href="#lists">Lists</a></li><li class="toc-level-3"><a href="#images">Images</a></li><li class="toc-level-3"><a href="#links">Links</a></li><li class="toc-level-3"><a href="#blockquotes">Blockquotes</a></li><li class="toc-level-3"><a href="#horizontal-rules">Horizontal Rules</a></li><li class="toc-level-3"><a href="#code">Code</a></li></ul></li><li class="toc-level-2"><a href="#markdown-in-rustyll">Markdown in Rustyll</a><ul><li class="toc-level-3"><a href="#front-matter">Front Matter</a></li><li class="toc-level-3"><a href="#enhanced-markdown-features">Enhanced Markdown Features</a></li><li class="toc-level-3"><a href="#markdown-processors">Markdown Processors</a></li></ul></li><li class="toc-level-2"><a href="#advanced-markdown-features">Advanced Markdown Features</a><ul><li class="toc-level-3"><a href="#markdown-includes">Markdown Includes</a></li><li class="toc-level-3"><a href="#conditional-markdown">Conditional Markdown</a></li><li class="toc-level-3"><a href="#markdown-variables">Markdown Variables</a></li></ul></li><li class="toc-level-2"><a href="#performance">Performance</a></li><li class="toc-level-2"><a href="#migration-from-jekyll">Migration from Jekyll</a></li>
</ul></nav>
</details><article class="prose prose-invert max-w-none"><p>Markdown is a lightweight markup language with plain text formatting syntax that Rustyll supports out of the box. This guide provides a quick introduction to Markdown for creating content in your Rustyll site.</p>
<h2 id="basic-markdown-syntax">Basic Markdown Syntax</h2>
<h3 id="headers">Headers</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># H1</span>
<span class="gu">## H2</span>
<span class="gu">### H3</span>
<span class="gu">#### H4</span>
<span class="gu">##### H5</span>
<span class="gu">###### H6</span>
</code></pre></div></div>
<h3 id="emphasis">Emphasis</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="ge">*This text will be italic*</span>
<span class="ge">_This will also be italic_</span>
<span class="gs">**This text will be bold**</span>
<span class="gs">__This will also be bold__</span>
<span class="ge">_You **can** combine them_</span>
</code></pre></div></div>
<h3 id="lists">Lists</h3>
<h4 id="unordered">Unordered</h4>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> Item 1
<span class="p">*</span> Item 2
<span class="p"> *</span> Item 2a
<span class="p"> *</span> Item 2b
</code></pre></div></div>
<h4 id="ordered">Ordered</h4>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span> Item 1
<span class="p">2.</span> Item 2
<span class="p">3.</span> Item 3
<span class="p"> 1.</span> Item 3a
<span class="p"> 2.</span> Item 3b
</code></pre></div></div>
<h3 id="images">Images</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">![</span><span class="nv">Alt Text</span><span class="p">](</span><span class="sx">url</span><span class="p">)</span>
</code></pre></div></div>
<h3 id="links">Links</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">[</span><span class="nv">Link Text</span><span class="p">](</span><span class="sx">url</span><span class="p">)</span>
</code></pre></div></div>
<h3 id="blockquotes">Blockquotes</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gt">&gt; This is a blockquote.</span>
<span class="gt">&gt; </span>
<span class="gt">&gt; This is the second paragraph in the blockquote.</span>
</code></pre></div></div>
<h3 id="horizontal-rules">Horizontal Rules</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">---
</span></code></pre></div></div>
<h3 id="code">Code</h3>
<p>Inline code uses single backticks:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Use the <span class="sb">`print()`</span> function
</code></pre></div></div>
<p>Code blocks use triple backticks with optional language specification:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">```</span><span class="nl">rust
</span><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
<span class="nd">println!</span><span class="p">(</span><span class="s">"Hello, world!"</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">```</span>
</code></pre></div></div>
<h2 id="markdown-in-rustyll">Markdown in Rustyll</h2>
<p>Rustyll uses Markdown for content files like posts and pages. When you create a new file with a <code class="language-plaintext highlighter-rouge">.md</code> or <code class="language-plaintext highlighter-rouge">.markdown</code> extension, Rustyll will convert it to HTML during the build process.</p>
<h3 id="front-matter">Front Matter</h3>
<p>Rustyll pages and posts require front matter. This is a section at the top of your markdown file that specifies metadata:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
<span class="na">layout</span><span class="pi">:</span> <span class="s">post</span>
<span class="na">title</span><span class="pi">:</span> <span class="s2">"</span><span class="s">My</span><span class="nv"> </span><span class="s">First</span><span class="nv"> </span><span class="s">Post"</span>
<span class="na">date</span><span class="pi">:</span> <span class="s">2023-06-15</span>
<span class="na">categories</span><span class="pi">:</span> <span class="s">tutorial</span>
<span class="na">parallel</span><span class="pi">:</span> <span class="kc">true</span> <span class="c1"># Enable parallel processing for this document</span>
<span class="na">render_priority</span><span class="pi">:</span> <span class="m">1</span> <span class="c1"># Higher priority in the build queue (lower number = higher priority)</span>
<span class="na">cache</span><span class="pi">:</span> <span class="s">aggressive</span> <span class="c1"># Cache this document aggressively</span>
<span class="nn">---</span>
</code></pre></div></div>
<h3 id="enhanced-markdown-features">Enhanced Markdown Features</h3>
<p>Rustyll enhances standard Markdown with several features:</p>
<ol>
<li><strong>Parallel Processing</strong>: Markdown files can be processed in parallel for speed</li>
<li><strong>Syntax Highlighting</strong>: Code blocks are automatically highlighted using a fast Rust-based highlighter</li>
<li><strong>Table of Contents</strong>: Generate a TOC with <code class="language-plaintext highlighter-rouge">{:toc}</code></li>
<li><strong>Custom Attributes</strong>: Add classes, IDs and other attributes to elements</li>
<li><strong>Math Rendering</strong>: Support for LaTeX math using <code class="language-plaintext highlighter-rouge">$$</code> delimiters</li>
<li><strong>Diagrams</strong>: Support for Mermaid and other diagram formats</li>
</ol>
<p>Example:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{: .warning}
<span class="gt">&gt; This is a warning message.</span>
<span class="p">
*</span> TOC
{:toc}
<span class="gh"># Header with ID {#custom-id}</span>
$$
<span class="se">\i</span>nt_0^1 x^2 dx = <span class="se">\f</span>rac{1}{3}
$$
<span class="p">```</span><span class="nl">mermaid
</span><span class="sb">graph TD;
A--&gt;B;
A--&gt;C;
B--&gt;D;
C--&gt;D;
</span></code></pre></div></div>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
### Performance Optimizations
Rustyll provides several Markdown-specific performance optimizations:
```yaml
# _config.yml
markdown:
parallel: true # Process markdown in parallel
cache: true # Cache rendered markdown
lazy_images: true # Lazy load images in markdown
incremental: true # Only reprocess changed markdown files
precompile_headers: true # Precompile headers for faster processing
threads: auto # Number of threads for markdown processing
</code></pre></div></div>
<p>You can also enable parallel processing for individual markdown files with front matter:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
<span class="na">title</span><span class="pi">:</span> <span class="s2">"</span><span class="s">My</span><span class="nv"> </span><span class="s">Document"</span>
<span class="na">parallel</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">render_priority</span><span class="pi">:</span> <span class="m">1</span>
<span class="nn">---</span>
</code></pre></div></div>
<h3 id="markdown-processors">Markdown Processors</h3>
<p>Rustyll uses <a href="https://github.com/kivikakk/comrak">Comrak</a> (a CommonMark parser written in Rust) by default, which offers significant performance improvements over Ruby-based Markdown processors.</p>
<p>You can configure the Markdown processor in your <code class="language-plaintext highlighter-rouge">_config.yml</code>:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">markdown</span><span class="pi">:</span> <span class="s">comrak</span>
<span class="na">comrak</span><span class="pi">:</span>
<span class="na">options</span><span class="pi">:</span>
<span class="na">hardbreaks</span><span class="pi">:</span> <span class="kc">false</span>
<span class="na">smart</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">github_pre_lang</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">extensions</span><span class="pi">:</span>
<span class="na">strikethrough</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">table</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">autolink</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">tasklist</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">superscript</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">header_ids</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">footnotes</span><span class="pi">:</span> <span class="kc">true</span>
</code></pre></div></div>
<h2 id="advanced-markdown-features">Advanced Markdown Features</h2>
<p>Rustyll supports several advanced Markdown features:</p>
<h3 id="markdown-includes">Markdown Includes</h3>
<p>Include other markdown files directly:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{% include_markdown _includes/snippet.md %}
</code></pre></div></div>
<h3 id="conditional-markdown">Conditional Markdown</h3>
<p>Show different content based on configuration:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{% if site.show_advanced_features %}
<span class="gh"># Advanced Features</span>
This content is only shown if advanced features are enabled.
{% endif %}
</code></pre></div></div>
<h3 id="markdown-variables">Markdown Variables</h3>
<p>Use site variables in your markdown:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>This site has {{ site.posts.size }} posts.
</code></pre></div></div>
<h2 id="performance">Performance</h2>
<p>Rustyll’s Markdown processing is significantly faster than Jekyll’s due to:</p>
<ol>
<li>Use of Comrak, a fast Rust-based CommonMark parser</li>
<li>Parallel processing of multiple Markdown files</li>
<li>Incremental builds that only reprocess changed files</li>
<li>Document-level caching</li>
<li>Header precompilation</li>
</ol>
<p>This means that even sites with hundreds of Markdown files can rebuild in milliseconds instead of seconds or minutes.</p>
<p>For the best performance:</p>
<ol>
<li>Enable parallel Markdown processing in your config</li>
<li>Use front matter <code class="language-plaintext highlighter-rouge">parallel: true</code> for complex documents</li>
<li>Set appropriate <code class="language-plaintext highlighter-rouge">render_priority</code> for critical pages</li>
<li>Use <code class="language-plaintext highlighter-rouge">cache: aggressive</code> for documents that rarely change</li>
</ol>
<h2 id="migration-from-jekyll">Migration from Jekyll</h2>
<p>Rustyll’s Markdown processing is fully compatible with Jekyll’s, so your existing Markdown content will work without changes. However, to take advantage of Rustyll’s performance optimizations, consider adding the Rustyll-specific front matter options mentioned above.</p>
</article>
<div class="doc-feedback"><p>Help keep these docs useful.</p>
<a href="https://github.com/betterwebinit/rustyll-website/edit/main/_docs/markdown-101.md"
target="_blank"
rel="noopener noreferrer"
class="inline-flex items-center gap-2 text-sm text-gray-400 hover:text-rust transition-colors duration-200 group px-3 py-1.5 bg-black/20 rounded-md border border-gray-800 hover:border-rust/30 ">
<svg class="w-4 h-4 transition-transform duration-200 group-hover:rotate-12" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path>
</svg>
<span>Improve this page</span>
</a> </div></div>
</div><aside class="docs-toc">
<nav class="page-toc " aria-label="On this page"><h2>On this page</h2><ul>
<li class="toc-level-2"><a href="#basic-markdown-syntax">Basic Markdown Syntax</a><ul><li class="toc-level-3"><a href="#headers">Headers</a></li><li class="toc-level-3"><a href="#emphasis">Emphasis</a></li><li class="toc-level-3"><a href="#lists">Lists</a></li><li class="toc-level-3"><a href="#images">Images</a></li><li class="toc-level-3"><a href="#links">Links</a></li><li class="toc-level-3"><a href="#blockquotes">Blockquotes</a></li><li class="toc-level-3"><a href="#horizontal-rules">Horizontal Rules</a></li><li class="toc-level-3"><a href="#code">Code</a></li></ul></li><li class="toc-level-2"><a href="#markdown-in-rustyll">Markdown in Rustyll</a><ul><li class="toc-level-3"><a href="#front-matter">Front Matter</a></li><li class="toc-level-3"><a href="#enhanced-markdown-features">Enhanced Markdown Features</a></li><li class="toc-level-3"><a href="#markdown-processors">Markdown Processors</a></li></ul></li><li class="toc-level-2"><a href="#advanced-markdown-features">Advanced Markdown Features</a><ul><li class="toc-level-3"><a href="#markdown-includes">Markdown Includes</a></li><li class="toc-level-3"><a href="#conditional-markdown">Conditional Markdown</a></li><li class="toc-level-3"><a href="#markdown-variables">Markdown Variables</a></li></ul></li><li class="toc-level-2"><a href="#performance">Performance</a></li><li class="toc-level-2"><a href="#migration-from-jekyll">Migration from Jekyll</a></li>
</ul></nav>
</aside></div></section>
--></span>
<span class="nt"></main></span>
<span class="nt"><footer></span>
<span class="c"><!-- <footer class="site-footer">
<div class="container">
<div class="footer-grid">
<div class="footer-updates">
<div>
<span class="footer-kicker">KEEP BUILDING</span>
<h2>Stay in the loop.</h2>
<p>Follow Rustyll releases and project news in the way that works for you.</p>
</div>
<div class="footer-update-actions">
<a class="footer-update-primary" href="/feed.xml">Follow the RSS feed <span aria-hidden="true">↗</span></a>
<a class="footer-update-secondary" href="https://github.com/betterwebinit/rustyll/releases">GitHub releases <span aria-hidden="true">↗</span></a>
</div>
</div>
<div class="footer-brand">
<div class="footer-brand-heading"><a href="/" class="brand " aria-label="Rustyll home"><img class="brand-original" src="/img/logo-2x.png" alt="Rustyll" width="113" height="55"></a>
<span>BETTER WEB PROJECT</span></div>
<p>A static site generator written in Rust. Built for a faster, more open web.</p>
<div class="footer-socials" aria-label="Follow Rustyll">
<a href="https://github.com/betterwebinit/rustyll" aria-label="Rustyll on GitHub"><svg aria-hidden="true" viewBox="0 0 24 24" fill="currentColor"><path d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.4 7.86 10.92.58.1.79-.25.79-.56 0-.28-.01-1.02-.02-2-3.2.7-3.88-1.54-3.88-1.54-.52-1.33-1.28-1.69-1.28-1.69-1.05-.72.08-.71.08-.71 1.16.08 1.77 1.19 1.77 1.19 1.03 1.77 2.7 1.26 3.36.96.1-.75.4-1.26.73-1.55-2.55-.29-5.23-1.28-5.23-5.69 0-1.26.45-2.29 1.19-3.1-.12-.29-.52-1.46.11-3.05 0 0 .97-.31 3.17 1.18a11 11 0 0 1 5.77 0c2.2-1.49 3.17-1.18 3.17-1.18.63 1.59.23 2.76.11 3.05.74.81 1.19 1.84 1.19 3.1 0 4.42-2.69 5.39-5.25 5.67.41.35.78 1.04.78 2.1 0 1.52-.01 2.74-.01 3.11 0 .31.21.67.8.56A11.51 11.51 0 0 0 23.5 12C23.5 5.65 18.35.5 12 .5Z"/></svg></a>
<a href="/feed.xml" aria-label="Rustyll RSS feed"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 5a15 15 0 0 1 15 15M4 11a9 9 0 0 1 9 9"/><circle cx="5" cy="19" r="1" fill="currentColor"/></svg></a>
<a href="https://better-web.org" aria-label="Better Web"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c-3 3-4 6-4 9s1 6 4 9m0-18c3 3 4 6 4 9s-1 6-4 9"/></svg></a>
</div>
</div>
<nav class="footer-links" aria-label="Build with Rustyll">
<h2>BUILD WITH RUSTYLL</h2>
<a href="/docs/"><span aria-hidden="true">↗</span>Documentation</a>
<a href="/tutorials/home/"><span aria-hidden="true">↗</span>Tutorials</a>
<a href="/docs/migrating/"><span aria-hidden="true">↗</span>Migration guides</a>
<a href="/docs/deployment/"><span aria-hidden="true">↗</span>Deployment</a>
<a href="/resources/"><span aria-hidden="true">↗</span>Resources</a>
</nav>
<nav class="footer-links" aria-label="The project">
<h2>THE PROJECT</h2>
<a href="/news/"><span aria-hidden="true">↗</span>News &amp; releases</a>
<a href="/docs/contributing/"><span aria-hidden="true">↗</span>Contributing</a>
<a href="/docs/support/"><span aria-hidden="true">↗</span>Support</a>
<a href="/philosophy/"><span aria-hidden="true">↗</span>Philosophy</a>
<a href="https://better-web.org"><span aria-hidden="true">↗</span>Better Web</a>
</nav>
</div>
<div class="footer-bottom"><p>© 2026 Rustyll. Part of the <a href="https://better-web.org">Better Web initiative</a>.</p><a href="#top">Back to top ↑</a></div>
</div>
</footer>
--></span>
<span class="nt"></footer></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</code></pre></div></div>
<h3 id="partials-to-includes">Partials to Includes</h3>
<p>Assemble’s partials convert to Rustyll includes:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Assemble (partials/header.hbs) --></span>
<span class="nt"><nav></span>
\{\{#each pages\}\}
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"\{\{this.url\}\}"</span> <span class="na">class=</span><span class="s">"\{\{#if this.isActive\}\}active\{\{/if\}\}"</span><span class="nt">></span>\{\{this.title\}\}<span class="nt"></a></span>
\{\{/each\}\}
<span class="nt"></nav></span>
</code></pre></div></div>
<p>Converts to:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Rustyll (_includes/header.html) --></span>
<span class="nt"><nav></span>
<span class="c"><!-- Liquid for loop starts --></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/404.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Page not found<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/github.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/issues.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/news/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>News<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/philosophy/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Philosophy<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/news/releases/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Releases<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/resources/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Resources<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/rustyllconf/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Talks and community learning<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/search/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Search<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/search.json"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/showcase/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>Community showcase<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/team/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></span>The people behind Rustyll<span class="nt"></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/conduct/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/help/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/conduct/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/configuration/webrick/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/deployment-methods/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/frontmatter/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/home/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/quickstart/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/extras/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/windows/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/templates/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/drafts/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/step-by-step/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/tutorials/index.html"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/resources/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/docs/sites/"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/redirects.json"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/feed/release.xml"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/feed.xml"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/sitemap.xml"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="nt"><a</span> <span class="na">href=</span><span class="s">"/robots.txt"</span> <span class="na">class=</span><span class="s">""</span><span class="nt">></a></span>
<span class="c"><!-- --></span>
<span class="c"><!-- Liquid for loop ends --></span>
<span class="nt"></nav></span>
</code></pre></div></div>
<h2 id="configuration-conversion">Configuration Conversion</h2>
<p>Assemble’s Grunt configuration converts to Rustyll’s YAML:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Assemble (Gruntfile.js)</span>
<span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">grunt</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">grunt</span><span class="p">.</span><span class="nf">initConfig</span><span class="p">({</span>
<span class="na">assemble</span><span class="p">:</span> <span class="p">{</span>
<span class="na">options</span><span class="p">:</span> <span class="p">{</span>
<span class="na">site</span><span class="p">:</span> <span class="p">{</span>
<span class="na">title</span><span class="p">:</span> <span class="dl">'</span><span class="s1">My Assemble Site</span><span class="dl">'</span><span class="p">,</span>
<span class="na">description</span><span class="p">:</span> <span class="dl">'</span><span class="s1">A website built with Assemble</span><span class="dl">'</span>
<span class="p">},</span>
<span class="na">layouts</span><span class="p">:</span> <span class="dl">'</span><span class="s1">templates/layouts</span><span class="dl">'</span><span class="p">,</span>
<span class="na">partials</span><span class="p">:</span> <span class="dl">'</span><span class="s1">templates/partials</span><span class="dl">'</span><span class="p">,</span>
<span class="na">data</span><span class="p">:</span> <span class="dl">'</span><span class="s1">data/*.{json,yml}</span><span class="dl">'</span>
<span class="p">},</span>
<span class="na">site</span><span class="p">:</span> <span class="p">{</span>
<span class="na">files</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span> <span class="na">expand</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="na">cwd</span><span class="p">:</span> <span class="dl">'</span><span class="s1">pages</span><span class="dl">'</span><span class="p">,</span> <span class="na">src</span><span class="p">:</span> <span class="dl">'</span><span class="s1">**/*.hbs</span><span class="dl">'</span><span class="p">,</span> <span class="na">dest</span><span class="p">:</span> <span class="dl">'</span><span class="s1">dist/</span><span class="dl">'</span> <span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="nx">grunt</span><span class="p">.</span><span class="nf">loadNpmTasks</span><span class="p">(</span><span class="dl">'</span><span class="s1">assemble</span><span class="dl">'</span><span class="p">);</span>
<span class="nx">grunt</span><span class="p">.</span><span class="nf">registerTask</span><span class="p">(</span><span class="dl">'</span><span class="s1">default</span><span class="dl">'</span><span class="p">,</span> <span class="p">[</span><span class="dl">'</span><span class="s1">assemble</span><span class="dl">'</span><span class="p">]);</span>
<span class="p">};</span>
</code></pre></div></div>
<p>Converts to:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Rustyll (_config.yml)</span>
<span class="na">title</span><span class="pi">:</span> <span class="s">My Assemble Site</span>
<span class="na">description</span><span class="pi">:</span> <span class="s">A website built with Assemble</span>
<span class="c1"># Directory settings</span>
<span class="na">layouts_dir</span><span class="pi">:</span> <span class="s">_layouts</span>
<span class="na">includes_dir</span><span class="pi">:</span> <span class="s">_includes</span>
<span class="c1"># Build settings</span>
<span class="na">markdown</span><span class="pi">:</span> <span class="s">commonmark</span>
<span class="na">permalink</span><span class="pi">:</span> <span class="s">pretty</span>
<span class="c1"># Performance settings</span>
<span class="na">threads</span><span class="pi">:</span> <span class="s">auto</span>
<span class="na">incremental</span><span class="pi">:</span> <span class="kc">true</span>
</code></pre></div></div>
<h2 id="data-system-conversion">Data System Conversion</h2>
<p>Assemble’s data file approach converts to Rustyll’s <code class="language-plaintext highlighter-rouge">_data</code> directory:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Assemble (data/team.yml)</span>
<span class="na">members</span><span class="pi">:</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">John Doe</span>
<span class="na">role</span><span class="pi">:</span> <span class="s">Developer</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Jane Smith</span>
<span class="na">role</span><span class="pi">:</span> <span class="s">Designer</span>
</code></pre></div></div>
<p>Transfers directly to:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Rustyll (_data/team.yml)</span>
<span class="na">members</span><span class="pi">:</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">John Doe</span>
<span class="na">role</span><span class="pi">:</span> <span class="s">Developer</span>
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Jane Smith</span>
<span class="na">role</span><span class="pi">:</span> <span class="s">Designer</span>
</code></pre></div></div>
<h2 id="helpers-to-filters-and-tags">Helpers to Filters and Tags</h2>
<p>Assemble’s custom helpers convert to Rustyll’s Liquid filters or includes:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Assemble (with custom helper) --></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"posts"</span><span class="nt">></span>
\{\{#each posts\}\}
<span class="nt"><article></span>
<span class="nt"><h2></span>\{\{title\}\}<span class="nt"></h2></span>
<span class="nt"><p></span>\{\{truncate description 100\}\}<span class="nt"></p></span>
<span class="nt"></article></span>
\{\{/each\}\}
<span class="nt"></div></span>
</code></pre></div></div>
<p>Converts to:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"><!-- Rustyll (with filter) --></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"posts"</span><span class="nt">></span>
<span class="c"><!-- Liquid for loop starts --></span>
<span class="c"><!-- --></span>
<span class="nt"><article></span>
<span class="nt"><h2></span>Rustyll v0.8.4 published<span class="nt"></h2></span>
<span class="nt"><p></span>The official Rustyll v0.8.4 release is available on GitHub.<span class="nt"></p></span>
<span class="nt"></article></span>
<span class="c"><!-- --></span>
<span class="c"><!-- Liquid for loop ends --></span>
<span class="nt"></div></span>
</code></pre></div></div>
<h2 id="collections">Collections</h2>
<p>Assemble’s post grouping can be implemented using Rustyll collections:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Rustyll (_config.yml)</span>
<span class="na">collections</span><span class="pi">:</span>
<span class="na">projects</span><span class="pi">:</span>
<span class="na">output</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">permalink</span><span class="pi">:</span> <span class="s">/projects/:path/</span>
</code></pre></div></div>
<p>With corresponding content files:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"><!-- Rustyll (_projects/project1.md) -->
---
</span>title: First Project
description: Description of first project
<span class="gh">featured: true
---
</span>
Content for first project goes here.
</code></pre></div></div>
<h2 id="performance-improvements">Performance Improvements</h2>
<p>Rustyll offers significant performance advantages over JavaScript-based Assemble:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Rustyll performance options</span>
<span class="na">threads</span><span class="pi">:</span> <span class="s">auto</span> <span class="c1"># Use all available CPU cores</span>
<span class="na">incremental</span><span class="pi">:</span> <span class="kc">true</span> <span class="c1"># Enable incremental builds</span>
<span class="na">cache</span><span class="pi">:</span>
<span class="na">enabled</span><span class="pi">:</span> <span class="kc">true</span>
<span class="na">strategy</span><span class="pi">:</span> <span class="s">aggressive</span>
</code></pre></div></div>
<p>Comparison:</p>
<ol>
<li><strong>Build Speed</strong>: 10-20x faster for large sites</li>
<li><strong>Memory Usage</strong>: Much lower RAM consumption</li>
<li><strong>Concurrency</strong>: Efficient use of all CPU cores</li>
</ol>
<h2 id="troubleshooting-common-issues">Troubleshooting Common Issues</h2>
<h3 id="template-syntax-differences">Template Syntax Differences</h3>
<p>If you encounter template conversion issues:</p>
<ol>
<li>Handlebars uses <code class="language-plaintext highlighter-rouge">\{\{variable\}\}</code> syntax while Liquid uses <code class="language-plaintext highlighter-rouge">{ { variable } }</code> (with spaces)</li>
<li>Handlebars helpers (<code class="language-plaintext highlighter-rouge">\{\{#each\}\}</code>) convert to Liquid tags (<code class="language-plaintext highlighter-rouge">{ % for % }</code>)</li>
<li>Handlebars context (<code class="language-plaintext highlighter-rouge">this</code>) is handled differently in Liquid</li>
</ol>
<h3 id="helper-functions">Helper Functions</h3>
<p>For complex Assemble helpers:</p>
<ol>
<li>Use Liquid’s built-in filters when possible</li>
<li>Create custom Liquid tags for complex functionality</li>
<li>Use JavaScript in the browser for dynamic components</li>
</ol>
<h3 id="layout-system">Layout System</h3>
<p>Assemble and Rustyll handle layouts differently:</p>
<ol>
<li>Assemble uses <code class="language-plaintext highlighter-rouge">\{\{> body\}\}</code> for content injection</li>
<li>Rustyll uses <code class="language-plaintext highlighter-rouge">{ { content } }</code> in layout files</li>
<li>Nested layouts work differently in Rustyll</li>
</ol>
<h2 id="migration-checklist">Migration Checklist</h2>
<ul class="task-list">
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Install Rust and Rustyll</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Back up your Assemble site</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Run the migration command</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Check template conversions</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Set up collections for content types</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Convert Handlebars helpers to Liquid filters</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Update asset references</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Configure permalink structure</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Test build with <code class="language-plaintext highlighter-rouge">rustyll build</code></li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Preview site with <code class="language-plaintext highlighter-rouge">rustyll serve</code></li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Fix any template or rendering issues</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Optimize performance settings</li>
<li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Update deployment workflows</li>
</ul>
<h2 id="need-help">Need Help?</h2>
<ul>
<li><a href="https://forum.rustyll.com">Rustyll Forum</a></li>
<li><a href="https://discord.gg/rustyll">Rustyll Discord</a></li>
<li><a href="https://github.com/rustyll/rustyll/issues">GitHub Issues</a></li>
</ul>
</article>
<nav class="doc-pagination" aria-label="Previous and next pages"><a href="/docs/migrating/"><span>← Previous</span>Migrating to Rustyll</a><a href="/docs/migrating/bridgetown-to-rustyll/"><span>Next →</span>Migrating from Bridgetown</a></nav>
<div class="doc-feedback"><p>Help keep these docs useful.</p>
<a href="https://github.com/betterwebinit/rustyll-website/edit/main/_docs/migrating/assemble-to-rustyll.md"
target="_blank"
rel="noopener noreferrer"
class="inline-flex items-center gap-2 text-sm text-gray-400 hover:text-rust transition-colors duration-200 group px-3 py-1.5 bg-black/20 rounded-md border border-gray-800 hover:border-rust/30 ">
<svg class="w-4 h-4 transition-transform duration-200 group-hover:rotate-12" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path>
</svg>
<span>Improve this page</span>
</a> </div></div>
</div><aside class="docs-toc">
<nav class="page-toc " aria-label="On this page"><h2>On this page</h2><ul>
<li class="toc-level-2"><a href="#installation">Installation</a></li><li class="toc-level-2"><a href="#automatic-migration">Automatic Migration</a></li><li class="toc-level-2"><a href="#directory-structure-differences">Directory Structure Differences</a></li><li class="toc-level-2"><a href="#content-conversion">Content Conversion</a></li><li class="toc-level-2"><a href="#template-conversion">Template Conversion</a><ul><li class="toc-level-3"><a href="#handlebars-to-liquid">Handlebars to Liquid</a></li><li class="toc-level-3"><a href="#partials-to-includes">Partials to Includes</a></li></ul></li><li class="toc-level-2"><a href="#configuration-conversion">Configuration Conversion</a></li><li class="toc-level-2"><a href="#data-system-conversion">Data System Conversion</a></li><li class="toc-level-2"><a href="#helpers-to-filters-and-tags">Helpers to Filters and Tags</a></li><li class="toc-level-2"><a href="#collections">Collections</a></li><li class="toc-level-2"><a href="#performance-improvements">Performance Improvements</a></li><li class="toc-level-2"><a href="#troubleshooting-common-issues">Troubleshooting Common Issues</a><ul><li class="toc-level-3"><a href="#template-syntax-differences">Template Syntax Differences</a></li><li class="toc-level-3"><a href="#helper-functions">Helper Functions</a></li><li class="toc-level-3"><a href="#layout-system">Layout System</a></li></ul></li><li class="toc-level-2"><a href="#migration-checklist">Migration Checklist</a></li><li class="toc-level-2"><a href="#need-help">Need Help?</a></li>
</ul></nav>
</aside></div></section>
-->
</div>
</div>
Converts to:
# Rustyll (_includes/shared/card.html)
<div class="card">
<h3><!-- --></h3>
<div class="content">
<!-- -->
</div>
</div>
Ruby Components
Bridgetown’s Ruby components convert to Liquid includes:
# Bridgetown (src/_components/shared/author_bio.rb)
class Shared::AuthorBio < Bridgetown::Component
def initialize(author:)
@author = site.data.authors[author]
end
end
# Bridgetown (src/_components/shared/author_bio.erb)
<div class="author-bio">
<h3><%= @author.name %></h3>
<p><%= @author.bio %></p>
</div>
Converts to:
# Rustyll (_includes/shared/author_bio.html)
<!-- -->
<div class="author-bio">
<h3><!-- --></h3>
<p><!-- --></p>
</div>
Asset Pipeline
Bridgetown’s esbuild/webpack assets convert to Rustyll’s asset structure:
| Bridgetown | Rustyll | Notes |
|---|---|---|
frontend/javascript/ |
assets/js/ |
JavaScript files |
frontend/styles/ |
_sass/ and assets/css/
|
CSS/SCSS files |
frontend/images/ |
assets/images/ |
Image files |
import statements |
Standard includes | Asset references |
Plugins
Bridgetown plugins convert to Rustyll plugins:
| Bridgetown Plugin | Rustyll Equivalent |
|---|---|
bridgetown-feed |
Built-in feed functionality |
bridgetown-seo-tag |
rustyll-seo |
bridgetown-sitemap |
rustyll-sitemap |
bridgetown-minify-html |
rustyll-minify-html |
| Ruby-based plugins | Rust-based plugins |
Performance Improvements
Rustyll offers significant performance advantages over Ruby-based Bridgetown:
# 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
Ruby Components
If you use Ruby components in Bridgetown:
- Convert to Liquid includes using the
includetag - Break complex components into smaller, more focused includes
- Use data files for dynamic configuration
Front-end Integration
If you rely on Bridgetown’s frontend integration:
- Move JavaScript to standard asset directories
- Configure scripts in individual HTML files
- Use simpler build processes for assets
Ruby Helpers
If you use Ruby helpers in Bridgetown:
- Look for equivalent Liquid filters in Rustyll
- Consider using custom Liquid filters via plugins
- Simplify template logic where possible
Content Collections
Bridgetown’s and Rustyll’s collections work similarly:
# _config.yml
collections:
products:
output: true
permalink: /products/:name/
sort_by: price
sort_direction: ascending
Migration Checklist
- Install Rust and Rustyll
- Back up your Bridgetown site
- Run the migration command
- Review content and front matter
- Check templates and includes
- Test component conversions
- Verify asset pipeline works
-
Build with
rustyll build -
Preview site with
rustyll serve - Test responsive design
- Fix any styling issues
- Update deployment workflows