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.
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 Assemble sites:
rustyll migrate --from assemble --source ./my-assemble-site --destination ./my-rustyll-site
This command will:
- Convert Assemble’s pages and templates to Rustyll format
- Transform Handlebars templates to Liquid templates
- Process YAML front matter
- Adapt Assemble’s data organization to Rustyll’s approach
- Generate a migration report
Directory Structure Differences
| Assemble | Rustyll | Notes |
|---|---|---|
pages/ |
Root directory | Content pages |
templates/ |
_layouts/ and _includes/ |
Templates are split by purpose |
partials/ |
_includes/ |
Reusable components |
data/ |
_data/ |
Data files (similar functionality) |
dist/ |
_site/ |
Generated site |
assets/ |
assets/ |
Static assets (same structure) |
Gruntfile.js |
_config.yml |
Configuration |
Content Conversion
Assemble pages with YAML front matter convert to Rustyll’s format:
<!-- Assemble (pages/about.hbs) -->
---
title: About Us
layout: default
---
<div class="about">
<h1>\{\{title\}\}</h1>
<p>This is the about page.</p>
</div>
Converts to:
<!-- Rustyll (about.html) -->
---
title: About Us
layout: default
---
<div class="about">
<h1>Migrating from Assemble</h1>
<p>This is the about page.</p>
</div>
Template Conversion
Handlebars to Liquid
Assemble’s Handlebars templates convert to Rustyll’s Liquid templates:
<!-- Assemble (templates/layouts/default.hbs) -->
<!DOCTYPE html>
<html>
<head>
<title>\{\{title\}\}</title>
<link rel="stylesheet" href="\{\{assets\}\}/css/style.css">
</head>
<body>
<header>
\{\{> header\}\}
</header>
<main>
\{\{> body\}\}
</main>
<footer>
\{\{> footer\}\}
</footer>
</body>
</html>
Converts to:
<!-- Rustyll (_layouts/default.html) -->
<!DOCTYPE html>
<html>
<head>
<title><!-- Migrating from Assemble --></title>
<link rel="stylesheet" href="<!-- /assets/css/style.css -->">
</head>
<body>
<header>
<!-- <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>
-->
</header>
<main>
<!-- <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>
</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">> This is a blockquote.</span>
<span class="gt">> </span>
<span class="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">> 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-->B;
A-->C;
B-->D;
C-->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>
-->
</main>
<footer>
<!-- <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 & 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>
-->
</footer>
</body>
</html>
Partials to Includes
Assemble’s partials convert to Rustyll includes:
<!-- Assemble (partials/header.hbs) -->
<nav>
\{\{#each pages\}\}
<a href="\{\{this.url\}\}" class="\{\{#if this.isActive\}\}active\{\{/if\}\}">\{\{this.title\}\}</a>
\{\{/each\}\}
</nav>
Converts to:
<!-- Rustyll (_includes/header.html) -->
<nav>
<!-- Liquid for loop starts -->
<!-- -->
<a href="/404.html" class="">Page not found</a>
<!-- -->
<a href="/github.html" class=""></a>
<!-- -->
<a href="/" class=""></a>
<!-- -->
<a href="/issues.html" class=""></a>
<!-- -->
<a href="/news/" class="">News</a>
<!-- -->
<a href="/philosophy/" class="">Philosophy</a>
<!-- -->
<a href="/news/releases/" class="">Releases</a>
<!-- -->
<a href="/resources/" class="">Resources</a>
<!-- -->
<a href="/rustyllconf/" class="">Talks and community learning</a>
<!-- -->
<a href="/search/" class="">Search</a>
<!-- -->
<a href="/search.json" class=""></a>
<!-- -->
<a href="/showcase/" class="">Community showcase</a>
<!-- -->
<a href="/team/" class="">The people behind Rustyll</a>
<!-- -->
<a href="/conduct/index.html" class=""></a>
<!-- -->
<a href="/help/index.html" class=""></a>
<!-- -->
<a href="/conduct/index.html" class=""></a>
<!-- -->
<a href="/docs/configuration/webrick/" class=""></a>
<!-- -->
<a href="/docs/deployment-methods/index.html" class=""></a>
<!-- -->
<a href="/docs/frontmatter/index.html" class=""></a>
<!-- -->
<a href="/docs/home/" class=""></a>
<!-- -->
<a href="/docs/quickstart/" class=""></a>
<!-- -->
<a href="/docs/extras/" class=""></a>
<!-- -->
<a href="/docs/windows/" class=""></a>
<!-- -->
<a href="/docs/templates/" class=""></a>
<!-- -->
<a href="/docs/drafts/" class=""></a>
<!-- -->
<a href="/docs/step-by-step/" class=""></a>
<!-- -->
<a href="/tutorials/index.html" class=""></a>
<!-- -->
<a href="/docs/resources/" class=""></a>
<!-- -->
<a href="/docs/sites/" class=""></a>
<!-- -->
<a href="/redirects.json" class=""></a>
<!-- -->
<a href="/feed/release.xml" class=""></a>
<!-- -->
<a href="/feed.xml" class=""></a>
<!-- -->
<a href="/sitemap.xml" class=""></a>
<!-- -->
<a href="/robots.txt" class=""></a>
<!-- -->
<!-- Liquid for loop ends -->
</nav>
Configuration Conversion
Assemble’s Grunt configuration converts to Rustyll’s YAML:
// Assemble (Gruntfile.js)
module.exports = function(grunt) {
grunt.initConfig({
assemble: {
options: {
site: {
title: 'My Assemble Site',
description: 'A website built with Assemble'
},
layouts: 'templates/layouts',
partials: 'templates/partials',
data: 'data/*.{json,yml}'
},
site: {
files: [
{ expand: true, cwd: 'pages', src: '**/*.hbs', dest: 'dist/' }
]
}
}
});
grunt.loadNpmTasks('assemble');
grunt.registerTask('default', ['assemble']);
};
Converts to:
# Rustyll (_config.yml)
title: My Assemble Site
description: A website built with Assemble
# Directory settings
layouts_dir: _layouts
includes_dir: _includes
# Build settings
markdown: commonmark
permalink: pretty
# Performance settings
threads: auto
incremental: true
Data System Conversion
Assemble’s data file approach converts to Rustyll’s _data directory:
# Assemble (data/team.yml)
members:
- name: John Doe
role: Developer
- name: Jane Smith
role: Designer
Transfers directly to:
# Rustyll (_data/team.yml)
members:
- name: John Doe
role: Developer
- name: Jane Smith
role: Designer
Helpers to Filters and Tags
Assemble’s custom helpers convert to Rustyll’s Liquid filters or includes:
<!-- Assemble (with custom helper) -->
<div class="posts">
\{\{#each posts\}\}
<article>
<h2>\{\{title\}\}</h2>
<p>\{\{truncate description 100\}\}</p>
</article>
\{\{/each\}\}
</div>
Converts to:
<!-- Rustyll (with filter) -->
<div class="posts">
<!-- Liquid for loop starts -->
<!-- -->
<article>
<h2>Rustyll v0.8.4 published</h2>
<p>The official Rustyll v0.8.4 release is available on GitHub.</p>
</article>
<!-- -->
<!-- Liquid for loop ends -->
</div>
Collections
Assemble’s post grouping can be implemented using Rustyll collections:
# Rustyll (_config.yml)
collections:
projects:
output: true
permalink: /projects/:path/
With corresponding content 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 JavaScript-based Assemble:
# Rustyll performance options
threads: auto # Use all available CPU cores
incremental: true # Enable incremental builds
cache:
enabled: true
strategy: aggressive
Comparison:
- Build Speed: 10-20x faster for large sites
- Memory Usage: Much lower RAM consumption
- Concurrency: Efficient use of all CPU cores
Troubleshooting Common Issues
Template Syntax Differences
If you encounter template conversion issues:
- Handlebars uses
\{\{variable\}\}syntax while Liquid uses{ { variable } }(with spaces) - Handlebars helpers (
\{\{#each\}\}) convert to Liquid tags ({ % for % }) - Handlebars context (
this) is handled differently in Liquid
Helper Functions
For complex Assemble helpers:
- Use Liquid’s built-in filters when possible
- Create custom Liquid tags for complex functionality
- Use JavaScript in the browser for dynamic components
Layout System
Assemble and Rustyll handle layouts differently:
- Assemble uses
\{\{> body\}\}for content injection - Rustyll uses
{ { content } }in layout files - Nested layouts work differently in Rustyll
Migration Checklist
- Install Rust and Rustyll
- Back up your Assemble site
- Run the migration command
- Check template conversions
- Set up collections for content types
- Convert Handlebars helpers to Liquid filters
- Update asset references
- Configure permalink structure
- Test build with
rustyll build - Preview site with
rustyll serve - Fix any template or rendering issues
- Optimize performance settings
- Update deployment workflows
