Migrating from Assemble

On this page

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:

  1. Convert Assemble’s pages and templates to Rustyll format
  2. Transform Handlebars templates to Liquid templates
  3. Process YAML front matter
  4. Adapt Assemble’s data organization to Rustyll’s approach
  5. 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><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>
 -->
  </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 &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>

 -->
  </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:

  1. Build Speed: 10-20x faster for large sites
  2. Memory Usage: Much lower RAM consumption
  3. Concurrency: Efficient use of all CPU cores

Troubleshooting Common Issues

Template Syntax Differences

If you encounter template conversion issues:

  1. Handlebars uses \{\{variable\}\} syntax while Liquid uses { { variable } } (with spaces)
  2. Handlebars helpers (\{\{#each\}\}) convert to Liquid tags ({ % for % })
  3. Handlebars context (this) is handled differently in Liquid

Helper Functions

For complex Assemble helpers:

  1. Use Liquid’s built-in filters when possible
  2. Create custom Liquid tags for complex functionality
  3. Use JavaScript in the browser for dynamic components

Layout System

Assemble and Rustyll handle layouts differently:

  1. Assemble uses \{\{> body\}\} for content injection
  2. Rustyll uses { { content } } in layout files
  3. 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

Need Help?

Search Rustyll

Type to find a page.