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="bg-black/95 backdrop-blur-sm border-b border-rust/20 py-2 sm:py-3 md:py-4 sticky top-0 z-50 transition-all duration-300 shadow-md" id="site-header">
<div class="container mx-auto px-4 flex flex-wrap items-center justify-between">
<div class="flex items-center">
<h1 class="mr-4 sm:mr-6">
<a href="/" class="flex items-center ">
<span class="sr-only">Rustyll</span>
<img src="/img/logo-2x.png" width="120" height="55" alt="Rustyll Logo"
class="h-10 w-auto transition-transform duration-300 hover:scale-105">
</a>
</h1>
</div>
<!-- Desktop Navigation -->
<nav class="hidden lg:flex items-center">
<ul class="flex items-center gap-2 ">
<li>
<a href="/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Home
</a>
</li>
<li>
<a href="/docs/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
bg-primary text-primary-foreground shadow hover:bg-primary/90
"
aria-current="page">
Docs
</a>
</li>
<li>
<a href="/resources/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Resources
</a>
</li>
<li>
<a href="/showcase/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Showcase
</a>
</li>
<li>
<a href="/news/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
News
</a>
</li>
</ul>
<style>
/* Add this to your global CSS or keep it here for component-specific styles */
:root {
--accent-rgb: 234, 88, 12; /* Adjust to match your accent color (this is for orange) */
}
@keyframes pulse-border {
0% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0.7); }
70% { box-shadow: 0 0 0 6px rgba(var(--accent-rgb), 0); }
100% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0); }
}
.animate-pulse-border {
animation: pulse-border 2s infinite;
}
</style>
</nav>
<!-- Tablet/Desktop Meta Links -->
<div class="hidden md:flex items-center gap-3 sm:gap-4">
<!-- Search -->
<div class="relative">
<div class="relative group">
<div class="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none text-gray-400 group-hover:text-rust transition-colors duration-200">
<svg class="w-4 h-4" aria-hidden="true" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
<input
type="text"
placeholder="Search the docs..."
aria-label="Search"
class="block w-full py-2 pl-10 pr-3 bg-black/30 border border-gray-700 rounded-md text-sm text-white placeholder-gray-400 focus:outline-none focus:border-rust focus:ring-1 focus:ring-rust transition-all duration-200 hover:border-gray-500 "
>
<div class="absolute inset-y-0 right-3 flex items-center pointer-events-none opacity-0 group-focus-within:opacity-100 transition-opacity duration-200">
<kbd class="hidden sm:inline-flex items-center px-1 py-0.5 text-xs bg-gray-800 border border-gray-700 rounded text-gray-400">⌘K</kbd>
</div>
</div>
</div>
<!-- Meta Links -->
<div class="flex items-center gap-2 sm:gap-3 md:gap-4 text-sm">
<a href="https://github.com/betterwebinit/rustyll/releases/tag/v0.1.0"
class="text-gray-400 hover:text-rust transition-all duration-200 transform hover:scale-105 text-sm group">
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white">v0.1.0</span>
</a>
<a href="https://github.com/betterwebinit/rustyll"
class="text-gray-400 hover:text-rust transition-all duration-200 flex items-center gap-1 transform hover:scale-105 group hidden sm:flex md:hidden lg:flex">
<svg class="w-5 h-5 text-gray-400 group-hover:text-rust" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.026 2.747-1.026.546 1.378.202 2.397.1 2.65.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd"></path>
</svg>
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white hidden xl:inline">GitHub</span>
</a>
<a href=""
class="text-gray-400 hover:text-rust transition-all duration-200 flex items-center gap-1 transform hover:scale-105 group hidden sm:flex md:hidden lg:flex">
<svg class="w-5 h-5 text-gray-400 group-hover:text-rust" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"></path>
</svg>
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white hidden xl:inline">Discord</span>
</a>
</div>
</div>
<!-- Tablet menu - Visible only on medium screens -->
<button type="button"
class="hidden md:inline-flex lg:hidden items-center justify-center p-2 rounded-md text-gray-400 hover:text-white hover:bg-rust/20 focus:outline-none transition-colors duration-200"
aria-expanded="false"
id="tablet-menu-button">
<span class="sr-only">Toggle navigation</span>
<svg class="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"></path>
</svg>
</button>
<!-- Mobile menu button -->
<button type="button"
class="md:hidden inline-flex items-center justify-center p-2 rounded-md text-gray-400 hover:text-white hover:bg-rust/20 focus:outline-none transition-colors duration-200"
aria-expanded="false"
id="mobile-menu-button">
<span class="sr-only">Open main menu</span>
<!-- Icon when menu is closed -->
<svg class="h-6 w-6 menu-closed" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"></path>
</svg>
<!-- Icon when menu is open -->
<svg class="h-6 w-6 menu-open hidden" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
</svg>
</button>
</div>
<!-- Tablet Navigation Dropdown -->
<nav class="hidden bg-black/95 backdrop-blur-sm border-t border-rust/10 mt-2 scale-y-95 origin-top transition-all duration-300 opacity-0" id="tablet-menu">
<div class="container mx-auto px-4 py-3">
<div class="grid grid-cols-3 gap-4">
<ul class="flex items-center gap-2 ">
<li>
<a href="/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Home
</a>
</li>
<li>
<a href="/docs/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
bg-primary text-primary-foreground shadow hover:bg-primary/90
"
aria-current="page">
Docs
</a>
</li>
<li>
<a href="/resources/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Resources
</a>
</li>
<li>
<a href="/showcase/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
Showcase
</a>
</li>
<li>
<a href="/news/"
class="inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 h-9 px-4 py-2
text-muted-foreground hover:bg-accent hover:text-accent-foreground
"
>
News
</a>
</li>
</ul>
<style>
/* Add this to your global CSS or keep it here for component-specific styles */
:root {
--accent-rgb: 234, 88, 12; /* Adjust to match your accent color (this is for orange) */
}
@keyframes pulse-border {
0% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0.7); }
70% { box-shadow: 0 0 0 6px rgba(var(--accent-rgb), 0); }
100% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0); }
}
.animate-pulse-border {
animation: pulse-border 2s infinite;
}
</style>
</div>
</div>
</nav>
<!-- Mobile Navigation -->
<nav class="md:hidden hidden bg-black/95 backdrop-blur-sm border-t border-rust/10 mt-1 scale-y-95 origin-top transition-all duration-300 opacity-0" id="mobile-menu">
<div class="container mx-auto px-4 pb-4 pt-2">
<div class="space-y-1 py-2 ">
<a
href="/"
class="block px-4 py-2 rounded-md transition-all duration-300 relative overflow-hidden
text-gray-300 hover:text-white before:absolute before:inset-0 before:bg-rust/10 before:scale-0 before:transition-transform before:duration-300 hover:before:scale-100
"
>
<div class="flex items-center relative z-10">
Home
</div>
</a>
<a
href="/docs/"
class="block px-4 py-2 rounded-md transition-all duration-300 relative overflow-hidden
text-white font-bold before:absolute before:inset-0 before:bg-rust/20 before:scale-100 before:animate-pulse before:animate-duration-[3000ms]
"
>
<div class="flex items-center relative z-10">
Docs
</div>
</a>
<a
href="/resources/"
class="block px-4 py-2 rounded-md transition-all duration-300 relative overflow-hidden
text-gray-300 hover:text-white before:absolute before:inset-0 before:bg-rust/10 before:scale-0 before:transition-transform before:duration-300 hover:before:scale-100
"
>
<div class="flex items-center relative z-10">
Resources
</div>
</a>
<a
href="/showcase/"
class="block px-4 py-2 rounded-md transition-all duration-300 relative overflow-hidden
text-gray-300 hover:text-white before:absolute before:inset-0 before:bg-rust/10 before:scale-0 before:transition-transform before:duration-300 hover:before:scale-100
"
>
<div class="flex items-center relative z-10">
Showcase
</div>
</a>
<a
href="/news/"
class="block px-4 py-2 rounded-md transition-all duration-300 relative overflow-hidden
text-gray-300 hover:text-white before:absolute before:inset-0 before:bg-rust/10 before:scale-0 before:transition-transform before:duration-300 hover:before:scale-100
"
>
<div class="flex items-center relative z-10">
News
</div>
</a>
<!-- Mobile search -->
<div class="px-3 py-3 border-t border-gray-700/30 mt-2">
<div class="relative group">
<div class="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none text-gray-400 group-hover:text-rust transition-colors duration-200">
<svg class="w-4 h-4" aria-hidden="true" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
<input
type="text"
placeholder="Search docs..."
aria-label="Search"
class="block w-full py-2 pl-10 pr-3 bg-black/30 border border-gray-700 rounded-md text-sm text-white placeholder-gray-400 focus:outline-none focus:border-rust focus:ring-1 focus:ring-rust transition-all duration-200 hover:border-gray-500 bg-black/50"
>
<div class="absolute inset-y-0 right-3 flex items-center pointer-events-none opacity-0 group-focus-within:opacity-100 transition-opacity duration-200">
<kbd class="hidden sm:inline-flex items-center px-1 py-0.5 text-xs bg-gray-800 border border-gray-700 rounded text-gray-400">⌘K</kbd>
</div>
</div>
</div>
<!-- Mobile meta links -->
<div class="flex flex-wrap gap-2 px-3 py-3 border-t border-gray-700/30">
<a href="https://github.com/betterwebinit/rustyll/releases/tag/v0.1.0"
class="px-3 py-1 bg-black/30 rounded-full text-sm text-gray-400 hover:text-rust transition flex items-center border border-gray-700/50 hover:border-rust/30">
<span>v0.1.0</span>
</a>
<a href="https://github.com/betterwebinit/rustyll"
class="px-3 py-1 bg-black/30 rounded-full text-sm text-gray-400 hover:text-rust transition flex items-center border border-gray-700/50 hover:border-rust/30">
<svg class="w-4 h-4 mr-1" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.026 2.747-1.026.546 1.378.202 2.397.1 2.65.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd"></path>
</svg>
<span>GitHub</span>
</a>
</div>
</div>
<!-- Mobile search -->
<div class="mt-4 relative">
<div class="relative group">
<div class="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none text-gray-400 group-hover:text-rust transition-colors duration-200">
<svg class="w-4 h-4" aria-hidden="true" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
<input
type="text"
placeholder="Search the docs..."
aria-label="Search"
class="block w-full py-2 pl-10 pr-3 bg-black/30 border border-gray-700 rounded-md text-sm text-white placeholder-gray-400 focus:outline-none focus:border-rust focus:ring-1 focus:ring-rust transition-all duration-200 hover:border-gray-500 "
>
<div class="absolute inset-y-0 right-3 flex items-center pointer-events-none opacity-0 group-focus-within:opacity-100 transition-opacity duration-200">
<kbd class="hidden sm:inline-flex items-center px-1 py-0.5 text-xs bg-gray-800 border border-gray-700 rounded text-gray-400">⌘K</kbd>
</div>
</div>
</div>
<!-- Mobile meta links -->
<div class="mt-4 flex justify-center">
<div class="flex items-center gap-2 sm:gap-3 md:gap-4 text-sm flex justify-center space-x-4">
<a href="https://github.com/betterwebinit/rustyll/releases/tag/v0.1.0"
class="text-gray-400 hover:text-rust transition-all duration-200 transform hover:scale-105 text-sm group">
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white">v0.1.0</span>
</a>
<a href="https://github.com/betterwebinit/rustyll"
class="text-gray-400 hover:text-rust transition-all duration-200 flex items-center gap-1 transform hover:scale-105 group hidden sm:flex md:hidden lg:flex">
<svg class="w-5 h-5 text-gray-400 group-hover:text-rust" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.026 2.747-1.026.546 1.378.202 2.397.1 2.65.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd"></path>
</svg>
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white hidden xl:inline">GitHub</span>
</a>
<a href=""
class="text-gray-400 hover:text-rust transition-all duration-200 flex items-center gap-1 transform hover:scale-105 group hidden sm:flex md:hidden lg:flex">
<svg class="w-5 h-5 text-gray-400 group-hover:text-rust" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"></path>
</svg>
<span class="group-hover:bg-clip-text group-hover:text-transparent group-hover:bg-gradient-to-r group-hover:from-rust group-hover:to-white hidden xl:inline">Discord</span>
</a>
</div>
</div>
</div>
</nav>
<script>
// Enhanced header behavior
document.addEventListener('DOMContentLoaded', function() {
const header = document.getElementById('site-header');
const mobileMenuBtn = document.getElementById('mobile-menu-button');
const mobileMenu = document.getElementById('mobile-menu');
const tabletMenuBtn = document.getElementById('tablet-menu-button');
const tabletMenu = document.getElementById('tablet-menu');
const menuClosedIcon = mobileMenuBtn.querySelector('.menu-closed');
const menuOpenIcon = mobileMenuBtn.querySelector('.menu-open');
let lastScrollTop = 0;
let isMobileMenuOpen = false;
let isTabletMenuOpen = false;
// Mobile menu toggle
mobileMenuBtn.addEventListener('click', function() {
isMobileMenuOpen = !isMobileMenuOpen;
if (!isMobileMenuOpen) {
mobileMenu.classList.add('hidden', 'scale-y-95', 'opacity-0');
mobileMenu.classList.remove('scale-y-100', 'opacity-100');
menuClosedIcon.classList.remove('hidden');
menuOpenIcon.classList.add('hidden');
} else {
// Close tablet menu if open
if (isTabletMenuOpen) {
toggleTabletMenu(false);
}
mobileMenu.classList.remove('hidden');
// Force a reflow to enable the transition
mobileMenu.offsetHeight;
mobileMenu.classList.add('scale-y-100', 'opacity-100');
mobileMenu.classList.remove('scale-y-95', 'opacity-0');
menuClosedIcon.classList.add('hidden');
menuOpenIcon.classList.remove('hidden');
}
});
// Tablet menu toggle
if (tabletMenuBtn) {
tabletMenuBtn.addEventListener('click', function() {
isTabletMenuOpen = !isTabletMenuOpen;
toggleTabletMenu(isTabletMenuOpen);
});
}
function toggleTabletMenu(isOpen) {
isTabletMenuOpen = isOpen;
if (!isOpen) {
tabletMenu.classList.add('hidden', 'scale-y-95', 'opacity-0');
tabletMenu.classList.remove('scale-y-100', 'opacity-100');
} else {
// Close mobile menu if open
if (isMobileMenuOpen) {
isMobileMenuOpen = false;
mobileMenu.classList.add('hidden', 'scale-y-95', 'opacity-0');
mobileMenu.classList.remove('scale-y-100', 'opacity-100');
menuClosedIcon.classList.remove('hidden');
menuOpenIcon.classList.add('hidden');
}
tabletMenu.classList.remove('hidden');
// Force a reflow to enable the transition
tabletMenu.offsetHeight;
tabletMenu.classList.add('scale-y-100', 'opacity-100');
tabletMenu.classList.remove('scale-y-95', 'opacity-0');
}
}
// Scroll behavior for header
window.addEventListener('scroll', function() {
const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
if (scrollTop > 100) {
header.classList.add('py-1', 'sm:py-2', 'md:py-3', 'bg-black/95');
header.classList.remove('py-2', 'sm:py-3', 'md:py-4');
} else {
header.classList.remove('py-1', 'sm:py-2', 'md:py-3', 'bg-black/95');
header.classList.add('py-2', 'sm:py-3', 'md:py-4');
}
// Hide header on scroll down, show on scroll up
if (scrollTop > lastScrollTop && scrollTop > 200 && !isMobileMenuOpen && !isTabletMenuOpen) {
// Scrolling down
header.classList.add('-translate-y-full');
} else {
// Scrolling up
header.classList.remove('-translate-y-full');
}
lastScrollTop = scrollTop;
});
// Close menus on window resize
window.addEventListener('resize', function() {
if (window.innerWidth >= 1024 && (isMobileMenuOpen || isTabletMenuOpen)) {
// Close mobile menu
if (isMobileMenuOpen) {
isMobileMenuOpen = false;
mobileMenu.classList.add('hidden', 'scale-y-95', 'opacity-0');
mobileMenu.classList.remove('scale-y-100', 'opacity-100');
menuClosedIcon.classList.remove('hidden');
menuOpenIcon.classList.add('hidden');
}
// Close tablet menu
if (isTabletMenuOpen) {
isTabletMenuOpen = false;
tabletMenu.classList.add('hidden', 'scale-y-95', 'opacity-0');
tabletMenu.classList.remove('scale-y-100', 'opacity-100');
}
}
});
// Keyboard shortcut for search
document.addEventListener('keydown', function(e) {
if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
e.preventDefault();
// Focus search input
document.querySelector('input[placeholder*="Search"]').focus();
}
});
});
</script>
</header>
-->
</header>
<main>
<!-- <section class="py-8 md:py-12 relative">
<!-- Background effects -->
<div class="absolute -top-40 -right-40 w-80 h-80 bg-rust/5 rounded-full blur-3xl"></div>
<div class="absolute -bottom-20 -left-20 w-60 h-60 bg-rust/5 rounded-full blur-3xl"></div>
<div class="container mx-auto px-4">
<!-- Mobile navigation -->
<div class="lg:hidden">
<div class="bg-gray-900/30 rounded-lg border border-gray-800 overflow-hidden mb-6 shadow-md ">
<details class="group" id="mobile-docs-menu">
<summary class="flex justify-between items-center cursor-pointer px-4 py-3 bg-black/30 border-b border-gray-800 hover:bg-black/40 transition-colors duration-200">
<div class="flex items-center">
<svg class="w-5 h-5 text-rust mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h7"></path>
</svg>
<h3 class="text-white font-medium">Markdown 101</h3>
</div>
<div class="flex items-center gap-2">
<span class="text-xs text-gray-400 hidden sm:inline-block">Browse</span>
<svg class="h-5 w-5 text-rust group-open:rotate-180 transition-transform duration-300" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path>
</svg>
</div>
</summary>
<div class="border-b border-gray-800">
<!-- Search input -->
<div class="p-3 bg-black/10">
<div class="relative">
<div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
<svg class="h-4 w-4 text-gray-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
<input id="mobile-doc-search" type="search" placeholder="Find in docs..."
class="w-full pl-10 pr-4 py-2 border border-gray-700 bg-black/30 rounded-md text-sm text-white placeholder-gray-500 focus:outline-none focus:border-rust">
</div>
</div>
<!-- Navigation tabs -->
<div class="flex border-b border-gray-800">
<button type="button" class="flex-1 py-2 px-4 text-white bg-black/30 font-medium text-sm focus:outline-none border-b-2 border-rust" data-tab="contents">
Contents
</button>
<button type="button" class="flex-1 py-2 px-4 text-gray-400 font-medium text-sm focus:outline-none hover:text-white transition-colors" data-tab="sections">
On This Page
</button>
</div>
<!-- Contents tab -->
<div class="p-3 max-h-72 overflow-y-auto tab-panel" id="tab-contents">
<div class="block lg:hidden w-full mb-6">
<select
id="doc-nav"
onchange="navigateToUrl(this)"
aria-label="Select a page from the documentation"
class="w-full px-3 py-2 bg-black/30 border border-gray-700 rounded-md text-white focus:outline-none focus:border-rust focus:ring-1 focus:ring-rust"
>
<option value="">Navigate the docs…</option>
<optgroup label="Getting Started">
<option value="/docs/">Quickstart</option>
<option value="/docs/installation/">Installation</option>
<option value="/docs/rust-101/">Rust 101 for Rustyll Users</option>
<option value="/docs/community/">Community</option>
<option value="/docs/step-by-step/01-setup/">Step by Step Tutorial</option>
</optgroup>
<optgroup label="Build">
<option value="/docs/usage/">Command Line Usage</option>
<option value="/docs/configuration/">Configuration</option>
<option value="/docs/rendering-process/">Rendering Process</option>
</optgroup>
<optgroup label="Content">
<option value="/docs/pages/">Pages</option>
<option value="/docs/posts/">Posts</option>
<option value="/docs/front-matter/">Front Matter</option>
<option value="/docs/collections/">Collections</option>
<option value="/docs/datafiles/">Data Files</option>
<option value="/docs/assets/">Assets</option>
<option value="/docs/static-files/">Static Files</option>
</optgroup>
<optgroup label="Site Structure">
<option value="/docs/structure/">Directory Structure</option>
<option value="/docs/liquid/">Liquid</option>
<option value="/docs/variables/">Variables</option>
<option value="/docs/includes/">Includes</option>
<option value="/docs/layouts/">Layouts</option>
<option value="/docs/permalinks/">Permalinks</option>
<option value="/docs/themes/">Themes</option>
<option value="/docs/pagination/">Pagination</option>
</optgroup>
<optgroup label="Guides">
<option value="/docs/plugins/">Plugins</option>
<option value="/docs/migrations/">Blog Migrations</option>
<option value="/docs/upgrading/">Upgrading</option>
<option value="/docs/deployment/">Deployment</option>
</optgroup>
<optgroup label="Migrating">
<option value="/docs/migrating/">Migrating to Rustyll</option>
<option value="/docs/migrating/assemble-to-rustyll/">Migrating from Assemble</option>
<option value="/docs/migrating/bridgetown-to-rustyll/">Migrating from Bridgetown</option>
<option value="/docs/migrating/cobalt-to-rustyll/">Migrating from Cobalt</option>
<option value="/docs/migrating/docsy-to-rustyll/">Migrating from Docsy</option>
<option value="/docs/migrating/eleventy-to-rustyll/">Migrating from Eleventy</option>
<option value="/docs/migrating/fresh-to-rustyll/">Migrating from Fresh</option>
<option value="/docs/migrating/gatsby-to-rustyll/">Migrating from Gatsby</option>
<option value="/docs/migrating/gitbook-to-rustyll/">Migrating from GitBook</option>
<option value="/docs/migrating/harp-to-rustyll/">Migrating from Harp</option>
<option value="/docs/migrating/hugo-to-rustyll/">Migrating from Hugo</option>
<option value="/docs/migrating/jekyll-to-rustyll/">Migrating from Jekyll</option>
<option value="/docs/migrating/mdbook-to-rustyll/">Migrating from mdBook</option>
<option value="/docs/migrating/middleman-to-rustyll/">Migrating from Middleman</option>
<option value="/docs/migrating/mkdocs-to-rustyll/">Migrating from MkDocs</option>
<option value="/docs/migrating/nanoc-to-rustyll/">Migrating from Nanoc</option>
<option value="/docs/migrating/pelican-to-rustyll/">Migrating from Pelican</option>
<option value="/docs/migrating/slate-to-rustyll/">Migrating from Slate</option>
<option value="/docs/migrating/zola-to-rustyll/">Migrating from Zola</option>
</optgroup>
</select>
</div>
</div>
<!-- Sections tab (hidden by default) -->
<div class="p-3 max-h-72 overflow-y-auto hidden tab-panel" id="tab-sections">
<div id="mobile-toc-container" class="text-sm">
<div class="text-gray-400">Loading sections...</div>
</div>
</div>
</div>
<!-- Quick links -->
<div class="p-3 flex flex-wrap gap-2 bg-gray-900/50">
<a href="/docs/" class="px-3 py-1.5 bg-black/30 rounded-full text-sm text-gray-400 hover:text-rust transition flex items-center border border-gray-700/50 hover:border-rust/30">
<svg class="w-3.5 h-3.5 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6"></path>
</svg>
<span>Home</span>
</a>
<a href="/docs/quickstart/" class="px-3 py-1.5 bg-black/30 rounded-full text-sm text-gray-400 hover:text-rust transition flex items-center border border-gray-700/50 hover:border-rust/30">
<svg class="w-3.5 h-3.5 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path>
</svg>
<span>Quickstart</span>
</a>
<a href="/docs/api/" class="px-3 py-1.5 bg-black/30 rounded-full text-sm text-gray-400 hover:text-rust transition flex items-center border border-gray-700/50 hover:border-rust/30">
<svg class="w-3.5 h-3.5 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"></path>
</svg>
<span>API</span>
</a>
</div>
</details>
<script>
document.addEventListener('DOMContentLoaded', function() {
// Tab switching
const tabButtons = document.querySelectorAll('[data-tab]');
const tabPanels = document.querySelectorAll('.tab-panel');
tabButtons.forEach(button => {
button.addEventListener('click', function() {
const tabId = this.getAttribute('data-tab');
// Update button states
tabButtons.forEach(btn => {
btn.classList.remove('text-white', 'bg-black/30', 'border-b-2', 'border-rust');
btn.classList.add('text-gray-400');
});
this.classList.add('text-white', 'bg-black/30', 'border-b-2', 'border-rust');
this.classList.remove('text-gray-400');
// Show/hide panels
tabPanels.forEach(panel => {
panel.classList.add('hidden');
});
document.getElementById(`tab-${tabId}`).classList.remove('hidden');
});
});
// Generate mobile TOC
const mobileTocContainer = document.getElementById('mobile-toc-container');
const headings = document.querySelectorAll('.prose h2, .prose h3');
if (headings.length === 0) {
mobileTocContainer.innerHTML = '<div class="text-sm text-gray-500 italic">No sections found</div>';
} else {
const toc = document.createElement('ul');
toc.className = 'space-y-1 text-sm';
headings.forEach((heading, index) => {
if (!heading.textContent.trim()) return;
// Add ID to heading if it doesn't have one
if (!heading.id) {
heading.id = 'heading-mobile-' + index;
}
const listItem = document.createElement('li');
const link = document.createElement('a');
const isH3 = heading.tagName.toLowerCase() === 'h3';
link.href = '#' + heading.id;
link.textContent = heading.textContent;
link.className = 'text-gray-400 hover:text-rust block py-1.5 px-2 hover:bg-black/20 rounded transition-colors' +
(isH3 ? ' ml-4 text-xs border-l border-gray-700 pl-2' : ' font-medium');
listItem.appendChild(link);
toc.appendChild(listItem);
// Add click handler for smooth scrolling
link.addEventListener('click', function(e) {
e.preventDefault();
// Close the mobile menu
document.getElementById('mobile-docs-menu').removeAttribute('open');
// Scroll to the heading
document.querySelector(this.getAttribute('href')).scrollIntoView({
behavior: 'smooth'
});
});
});
mobileTocContainer.innerHTML = '';
mobileTocContainer.appendChild(toc);
}
// Filter for mobile search
const mobileSearchInput = document.getElementById('mobile-doc-search');
if (mobileSearchInput) {
mobileSearchInput.addEventListener('input', function() {
const searchTerm = this.value.toLowerCase();
// Find all navigation links
const links = document.querySelectorAll('#tab-contents a');
links.forEach(link => {
const text = link.textContent.toLowerCase();
const listItem = link.closest('li');
if (text.includes(searchTerm)) {
listItem.style.display = '';
// Highlight matching text
if (searchTerm.length > 0) {
const regExp = new RegExp(searchTerm, 'gi');
const newText = link.textContent.replace(regExp, match => `<mark class="bg-rust/20 text-white">${match}</mark>`);
link.innerHTML = newText;
}
} else {
listItem.style.display = 'none';
}
});
});
}
});
</script>
</div>
</div>
<div class="flex flex-col lg:flex-row gap-6 lg:gap-8">
<!-- Sidebar column -->
<div class="lg:w-1/5 order-1 lg:sticky lg:self-start lg:top-24 lg:max-h-screen">
<div class="bg-gray-900/30 rounded-lg border border-gray-800 overflow-hidden h-[calc(100vh-180px)] flex flex-col ">
<div class="border-b border-gray-800 px-4 py-3 flex items-center bg-black/30">
<svg class="w-5 h-5 text-rust mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"></path>
</svg>
<h3 class="text-white font-medium">Documentation</h3>
</div>
<div class="p-3 overflow-y-auto flex-grow custom-scrollbar">
<div class="lg:block" id="docs-nav">
<div class="hidden lg:block">
<aside class="sticky top-8">
<h4 class="text-lg font-bold text-white mb-2">Getting Started</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Quickstart
</a>
</li>
<li class=""><a href="/docs/installation/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Installation
</a>
</li>
<li class=""><a href="/docs/rust-101/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Rust 101 for Rustyll Users
</a>
</li>
<li class=""><a href="/docs/community/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Community
</a>
</li>
<li class=""><a href="/docs/step-by-step/01-setup/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Step by Step Tutorial
</a>
</li>
</ul>
<h4 class="text-lg font-bold text-white mb-2">Build</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/usage/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Command Line Usage
</a>
</li>
<li class=""><a href="/docs/configuration/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Configuration
</a>
</li>
<li class=""><a href="/docs/rendering-process/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Rendering Process
</a>
</li>
</ul>
<h4 class="text-lg font-bold text-white mb-2">Content</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/pages/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Pages
</a>
</li>
<li class=""><a href="/docs/posts/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Posts
</a>
</li>
<li class=""><a href="/docs/front-matter/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Front Matter
</a>
</li>
<li class=""><a href="/docs/collections/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Collections
</a>
</li>
<li class=""><a href="/docs/datafiles/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Data Files
</a>
</li>
<li class=""><a href="/docs/assets/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Assets
</a>
</li>
<li class=""><a href="/docs/static-files/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Static Files
</a>
</li>
</ul>
<h4 class="text-lg font-bold text-white mb-2">Site Structure</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/structure/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Directory Structure
</a>
</li>
<li class=""><a href="/docs/liquid/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Liquid
</a>
</li>
<li class=""><a href="/docs/variables/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Variables
</a>
</li>
<li class=""><a href="/docs/includes/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Includes
</a>
</li>
<li class=""><a href="/docs/layouts/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Layouts
</a>
</li>
<li class=""><a href="/docs/permalinks/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Permalinks
</a>
</li>
<li class=""><a href="/docs/themes/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Themes
</a>
</li>
<li class=""><a href="/docs/pagination/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Pagination
</a>
</li>
</ul>
<h4 class="text-lg font-bold text-white mb-2">Guides</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/plugins/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Plugins
</a>
</li>
<li class=""><a href="/docs/migrations/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Blog Migrations
</a>
</li>
<li class=""><a href="/docs/upgrading/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Upgrading
</a>
</li>
<li class=""><a href="/docs/deployment/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Deployment
</a>
</li>
</ul>
<h4 class="text-lg font-bold text-white mb-2">Migrating</h4>
<ul class="space-y-1 mb-6">
<li class=""><a href="/docs/migrating/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating to Rustyll
</a>
</li>
<li class=""><a href="/docs/migrating/assemble-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Assemble
</a>
</li>
<li class=""><a href="/docs/migrating/bridgetown-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Bridgetown
</a>
</li>
<li class=""><a href="/docs/migrating/cobalt-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Cobalt
</a>
</li>
<li class=""><a href="/docs/migrating/docsy-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Docsy
</a>
</li>
<li class=""><a href="/docs/migrating/eleventy-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Eleventy
</a>
</li>
<li class=""><a href="/docs/migrating/fresh-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Fresh
</a>
</li>
<li class=""><a href="/docs/migrating/gatsby-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Gatsby
</a>
</li>
<li class=""><a href="/docs/migrating/gitbook-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from GitBook
</a>
</li>
<li class=""><a href="/docs/migrating/harp-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Harp
</a>
</li>
<li class=""><a href="/docs/migrating/hugo-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Hugo
</a>
</li>
<li class=""><a href="/docs/migrating/jekyll-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Jekyll
</a>
</li>
<li class=""><a href="/docs/migrating/mdbook-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from mdBook
</a>
</li>
<li class=""><a href="/docs/migrating/middleman-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Middleman
</a>
</li>
<li class=""><a href="/docs/migrating/mkdocs-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from MkDocs
</a>
</li>
<li class=""><a href="/docs/migrating/nanoc-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Nanoc
</a>
</li>
<li class=""><a href="/docs/migrating/pelican-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Pelican
</a>
</li>
<li class=""><a href="/docs/migrating/slate-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Slate
</a>
</li>
<li class=""><a href="/docs/migrating/zola-to-rustyll/" class="block py-1 text-gray-300 hover:text-rust transition-colors duration-200">
Migrating from Zola
</a>
</li>
</ul>
</aside>
</div>
</div>
</div>
<!-- Quick links -->
<div class="border-t border-gray-800 p-2 bg-black/10 hidden lg:flex flex-wrap gap-2 justify-center">
<a href="/docs/"
class="px-2 py-1 text-xs text-gray-400 hover:text-rust transition flex items-center gap-1 group">
<svg class="w-3 h-3 text-gray-500 group-hover:text-rust transition-colors" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6"></path>
</svg>
<span>Home</span>
</a>
<a href="/docs/quickstart/"
class="px-2 py-1 text-xs text-gray-400 hover:text-rust transition flex items-center gap-1 group">
<svg class="w-3 h-3 text-gray-500 group-hover:text-rust transition-colors" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path>
</svg>
<span>Quickstart</span>
</a>
</div>
<!-- Search docs -->
<div class="border-t border-gray-800 p-3 bg-black/20">
<div class="relative">
<div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
<svg class="h-4 w-4 text-gray-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
</svg>
</div>
<input type="search"
placeholder="Search docs..."
class="w-full pl-10 pr-3 py-1.5 border border-gray-700 bg-black/30 rounded-md text-sm text-white placeholder-gray-500 focus:outline-none focus:ring-1 focus:ring-rust focus:border-rust">
</div>
</div>
</div>
<style>
/* Custom scrollbar styles */
.custom-scrollbar::-webkit-scrollbar {
width: 6px;
}
.custom-scrollbar::-webkit-scrollbar-track {
background: rgba(0, 0, 0, 0.1);
}
.custom-scrollbar::-webkit-scrollbar-thumb {
background: rgba(180, 83, 9, 0.3);
border-radius: 3px;
}
.custom-scrollbar::-webkit-scrollbar-thumb:hover {
background: rgba(180, 83, 9, 0.5);
}
/* Enhanced sidebar navigation styles */
#docs-nav ul {
list-style: none;
padding-left: 0.5rem;
}
#docs-nav > ul {
padding-left: 0;
}
#docs-nav li {
margin-bottom: 0.25rem;
}
#docs-nav a {
display: block;
padding: 0.25rem 0.5rem;
border-radius: 0.25rem;
font-size: 0.875rem;
color: rgb(156 163 175);
transition: all 0.2s;
}
#docs-nav a:hover {
color: white;
background: rgba(180, 83, 9, 0.1);
}
#docs-nav a.current {
color: #fff;
background: rgba(180, 83, 9, 0.15);
border-left: 2px solid rgb(180, 83, 9);
font-weight: 500;
}
#docs-nav .active > a {
color: rgb(249, 115, 22);
font-weight: 500;
}
</style>
<script>
document.addEventListener('DOMContentLoaded', function() {
// Expand the current section
const currentPage = document.querySelector('.current');
if (currentPage) {
// Find parent list items and add active class
let parent = currentPage.parentElement;
while (parent && parent.tagName !== 'NAV') {
if (parent.tagName === 'LI') {
parent.classList.add('active');
// Expand any collapsed lists
const ul = parent.querySelector('ul');
if (ul) {
ul.style.display = 'block';
}
}
parent = parent.parentElement;
}
// Scroll to current page in sidebar
setTimeout(() => {
const sidebarContainer = document.querySelector('.overflow-y-auto');
if (sidebarContainer && currentPage) {
sidebarContainer.scrollTop = currentPage.offsetTop - sidebarContainer.offsetHeight / 3;
}
}, 100);
}
});
</script>
</div>
<!-- Main content column -->
<div class="lg:w-3/5 order-2">
<div class="relative bg-black/10 rounded-xl p-5 md:p-7 border border-gray-800 shadow-lg hover:shadow-rust/5 transition-shadow duration-300 ">
<div class="absolute -top-10 -right-10 w-40 h-40 bg-rust/5 rounded-full blur-3xl"></div>
<!-- Document meta information -->
<div class="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-3 py-3 mb-2 ">
<!-- Badge for docs type -->
<div class="flex items-center gap-2">
<span class="px-2 py-0.5 bg-rust/10 rounded-full text-rust text-xs border border-rust/30 whitespace-nowrap">
Documentation
</span>
<!-- Reading time estimation -->
<div class="flex items-center text-xs text-gray-400">
<svg class="w-3.5 h-3.5 mr-1 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"></path>
</svg>
<span>5 min read</span>
</div>
</div>
<div class="flex items-center gap-4">
<!-- Last updated date -->
<div class="flex items-center text-xs text-gray-400">
<svg class="w-3.5 h-3.5 mr-1 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"></path>
</svg>
<span>Updated: May 29, 2025</span>
</div>
<!-- Improve doc link -->
<div>
<a href="https://github.com/betterwebinit/rustyll/blob/master//opt/buildhome/repo/_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>
<!-- Document title -->
<h1 class="text-3xl md:text-4xl font-bold text-white relative group mb-6 pl-4">
<span class="bg-clip-text text-transparent bg-gradient-to-r from-white via-white to-gray-300">
Markdown 101
</span>
<div class="absolute -left-4 top-1/2 -translate-y-1/2 h-8 w-1.5 bg-gradient-to-b from-rust to-rust/50 rounded-r-full"></div>
<div class="mt-2 w-24 h-1 bg-gradient-to-r from-rust to-transparent rounded-full group-hover:w-32 transition-all duration-300"></div>
</h1>
<!-- Main content -->
<article class="prose prose-invert prose-lg max-w-none
/* Headings */
prose-headings:text-white prose-headings:font-medium prose-headings:scroll-mt-24
prose-h1:text-3xl prose-h1:font-bold prose-h1:mb-6 prose-h1:border-b prose-h1:border-gray-800 prose-h1:pb-4
prose-h2:text-2xl prose-h2:mt-10 prose-h2:mb-4 prose-h2:font-semibold
prose-h3:text-xl prose-h3:mt-8 prose-h3:mb-3
prose-h4:text-lg prose-h4:mt-6 prose-h4:mb-2
/* Links */
prose-a:text-rust prose-a:decoration-rust/30 prose-a:decoration-2 prose-a:underline-offset-2
hover:prose-a:text-rust-light hover:prose-a:decoration-rust-light/50 hover:prose-a:transition-colors
/* Code blocks */
prose-pre:bg-black/30 prose-pre:border prose-pre:border-gray-800 prose-pre:rounded-lg
prose-pre:my-6 prose-pre:shadow-md prose-pre:p-4 prose-pre:overflow-auto
/* Inline code */
prose-code:text-rust-light prose-code:bg-black/30 prose-code:px-1.5 prose-code:py-0.5
prose-code:rounded prose-code:text-sm prose-code:font-mono
/* Images */
prose-img:rounded-lg prose-img:border prose-img:border-gray-800 prose-img:shadow-md
prose-img:my-8 prose-img:max-w-full prose-img:mx-auto
/* Lists */
prose-li:marker:text-rust prose-li:my-1 prose-ol:pl-6 prose-ul:pl-6
prose-li:pl-2
/* Blockquotes */
prose-blockquote:border-l-4 prose-blockquote:border-rust prose-blockquote:bg-black/20
prose-blockquote:pl-6 prose-blockquote:py-2 prose-blockquote:pr-4 prose-blockquote:rounded-r-md
prose-blockquote:text-gray-300 prose-blockquote:not-italic prose-blockquote:my-6
/* Horizontal rules */
prose-hr:border-gray-800 prose-hr:my-10
/* Strong text */
prose-strong:text-white prose-strong:font-semibold
/* Tables */
prose-table:border-collapse prose-table:w-full prose-table:my-8
prose-table:border prose-table:border-gray-800 prose-table:shadow-sm
prose-td:border prose-td:border-gray-800 prose-td:p-2 prose-td:align-top
prose-th:border prose-th:border-gray-800 prose-th:p-3 prose-th:bg-black/30
prose-th:text-left prose-th:font-medium">
<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">> 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>
<!-- Mobile Table of Contents -->
<div class="mt-8 lg:hidden">
<div class="bg-gray-900/30 rounded-lg border border-gray-800 overflow-hidden sticky top-24 ">
<div class="border-b border-gray-800 px-4 py-2.5 flex items-center bg-black/30">
<svg class="w-4 h-4 text-rust mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h7"></path>
</svg>
<h3 class="text-white font-medium text-sm">On this page</h3>
</div>
<div class="px-3 py-3 max-h-[calc(100vh-260px)] overflow-y-auto custom-scrollbar" id="table-of-contents">
<ul class="space-y-1 text-sm pr-2">
<li>
<a href="#basic-markdown-syntax" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Basic Markdown Syntax
</a>
</li>
<li>
<a href="#markdown-in-rustyll" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Markdown in Rustyll
</a>
</li>
<li>
<a href="#advanced-markdown-features" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Advanced Markdown Features
</a>
</li>
<li>
<a href="#performance" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Performance
</a>
</li>
<li>
<a href="#migration-from-jekyll" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Migration from Jekyll
</a>
</li>
</ul>
</div>
<style>
/* Active TOC item styles */
#table-of-contents .active-link {
color: rgb(249, 115, 22) !important;
font-weight: 500;
transform: translateX(3px);
}
#table-of-contents a {
position: relative;
transition: all 0.2s ease;
}
#table-of-contents .active-link::before {
content: "";
position: absolute;
left: -10px;
top: 50%;
transform: translateY(-50%);
height: 5px;
width: 5px;
border-radius: 50%;
background-color: rgb(249, 115, 22);
}
</style>
<script>
document.addEventListener('DOMContentLoaded', function() {
const tocLinks = document.querySelectorAll('#table-of-contents a');
// Add click handler for smooth scrolling
tocLinks.forEach(link => {
link.addEventListener('click', function(e) {
e.preventDefault();
document.querySelector(this.getAttribute('href')).scrollIntoView({
behavior: 'smooth'
});
});
});
// Highlight current section on scroll
window.addEventListener('scroll', function() {
const scrollPos = window.scrollY;
tocLinks.forEach(link => {
const targetId = link.getAttribute('href').substring(1);
const targetElement = document.getElementById(targetId);
if (targetElement) {
const rect = targetElement.getBoundingClientRect();
if (rect.top <= 100 && rect.bottom >= 100) {
tocLinks.forEach(l => l.classList.remove('active-link'));
link.classList.add('active-link');
}
}
});
});
});
</script>
</div>
</div>
<!-- Navigation between pages -->
<div class="flex items-center justify-between space-x-4 pt-6 mt-12 border-t border-gray-800 mt-8">
<div></div>
<div></div>
</div>
<!-- Edit suggestion -->
<div class="mt-12 bg-gray-900/30 rounded-lg p-6 border border-gray-800 flex flex-col md:flex-row items-center gap-4 justify-between">
<div>
<h3 class="text-white font-medium mb-1">Found an issue with this page?</h3>
<p class="text-gray-400 text-sm">Help us improve the documentation by submitting a pull request.</p>
</div>
<a href="https://github.com/betterwebinit/rustyll/blob/master//opt/buildhome/repo/_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>
<!-- Table of contents column -->
<div class="lg:w-1/5 order-3 hidden lg:block lg:sticky lg:self-start lg:top-24 lg:max-h-screen">
<div class="bg-gray-900/30 rounded-lg border border-gray-800 overflow-hidden sticky top-24 ">
<div class="border-b border-gray-800 px-4 py-2.5 flex items-center bg-black/30">
<svg class="w-4 h-4 text-rust mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h7"></path>
</svg>
<h3 class="text-white font-medium text-sm">On this page</h3>
</div>
<div class="px-3 py-3 max-h-[calc(100vh-260px)] overflow-y-auto custom-scrollbar" id="table-of-contents">
<ul class="space-y-1 text-sm pr-2">
<li>
<a href="#basic-markdown-syntax" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Basic Markdown Syntax
</a>
</li>
<li>
<a href="#markdown-in-rustyll" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Markdown in Rustyll
</a>
</li>
<li>
<a href="#advanced-markdown-features" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Advanced Markdown Features
</a>
</li>
<li>
<a href="#performance" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Performance
</a>
</li>
<li>
<a href="#migration-from-jekyll" class="text-gray-400 hover:text-rust transition-colors duration-200 block px-2 py-1 hover:bg-black/20 rounded font-medium">
Migration from Jekyll
</a>
</li>
</ul>
</div>
<style>
/* Active TOC item styles */
#table-of-contents .active-link {
color: rgb(249, 115, 22) !important;
font-weight: 500;
transform: translateX(3px);
}
#table-of-contents a {
position: relative;
transition: all 0.2s ease;
}
#table-of-contents .active-link::before {
content: "";
position: absolute;
left: -10px;
top: 50%;
transform: translateY(-50%);
height: 5px;
width: 5px;
border-radius: 50%;
background-color: rgb(249, 115, 22);
}
</style>
<script>
document.addEventListener('DOMContentLoaded', function() {
const tocLinks = document.querySelectorAll('#table-of-contents a');
// Add click handler for smooth scrolling
tocLinks.forEach(link => {
link.addEventListener('click', function(e) {
e.preventDefault();
document.querySelector(this.getAttribute('href')).scrollIntoView({
behavior: 'smooth'
});
});
});
// Highlight current section on scroll
window.addEventListener('scroll', function() {
const scrollPos = window.scrollY;
tocLinks.forEach(link => {
const targetId = link.getAttribute('href').substring(1);
const targetElement = document.getElementById(targetId);
if (targetElement) {
const rect = targetElement.getBoundingClientRect();
if (rect.top <= 100 && rect.bottom >= 100) {
tocLinks.forEach(l => l.classList.remove('active-link'));
link.classList.add('active-link');
}
}
});
});
});
</script>
</div>
</div>
</div>
</div>
</section>
-->
</main>
<footer>
<!--
<footer class="bg-black py-12 border-t border-rust/20 relative overflow-hidden">
<!-- Background effect -->
<div class="absolute inset-0 bg-gradient-to-b from-black to-black/90"></div>
<div class="absolute top-0 left-0 w-full h-1 bg-gradient-to-r from-transparent via-rust/30 to-transparent"></div>
<div class="absolute -bottom-40 -left-40 w-80 h-80 bg-rust/5 rounded-full blur-3xl"></div>
<div class="absolute -top-20 -right-20 w-60 h-60 bg-rust/5 rounded-full blur-3xl"></div>
<div class="container mx-auto px-4 relative z-10">
<div class="grid grid-cols-1 md:grid-cols-12 gap-8 lg:gap-12 mb-8">
<!-- Main info column -->
<div class="md:col-span-5">
<div class="relative ">
<!-- Logo with glow effect -->
<div class="mb-4">
<a href="/" class="flex items-center mb-4">
<span class="sr-only">Rustyll</span>
<img src="/img/logo-2x.png" width="120" height="55" alt="Rustyll Logo"
class="h-10 w-auto transition-transform duration-300 hover:scale-105">
</a>
<div class="absolute -top-6 -left-6 w-32 h-32 bg-rust/10 rounded-full blur-3xl"></div>
</div>
<!-- Team info -->
<p class="text-gray-400 mb-3 text-lg">
Rustyll is lovingly maintained by the
<a href="/team/"
class="text-rust hover:text-rust-light transition-all duration-200 hover:underline decoration-rust/40 relative inline-flex group">
core team
<span class="absolute -bottom-1 left-0 w-full h-0.5 bg-rust/30 transform scale-x-0 group-hover:scale-x-100 transition-transform duration-300 origin-bottom-left"></span>
</a>
of volunteers.
</p>
<!-- Copyright -->
<p class="text-gray-400 text-sm mb-6">
© 2025 under the terms of the
<a href="https://github.com/betterwebinit/rustyll/blob/master/LICENSE"
class="text-rust hover:text-rust-light transition-all duration-200 hover:underline decoration-rust/40">
MIT License
</a>
</p>
<!-- Newsletter signup -->
<div class="mt-6 relative overflow-hidden rounded-xl border border-rust/20 p-5 bg-black/20 backdrop-blur-sm hover:bg-black/30 transition-all duration-300">
<div class="absolute -top-10 -right-10 w-40 h-40 bg-rust/5 rounded-full blur-3xl"></div>
<h3 class="text-white font-medium mb-2">Stay updated</h3>
<p class="text-gray-400 text-sm mb-4">Join our newsletter for the latest Rustyll updates</p>
<form class="flex flex-col sm:flex-row gap-2">
<input type="email"
placeholder="Your email address"
class="flex-grow bg-black/30 border border-gray-700 rounded-md text-sm text-white placeholder-gray-400 focus:outline-none focus:border-rust focus:ring-1 focus:ring-rust px-3 py-2">
<button type="submit"
class="bg-rust hover:bg-rust-light text-white rounded-md px-4 py-2 text-sm font-medium transition-all duration-200 transform hover:translate-y-[-2px]">
Subscribe
</button>
</form>
</div>
</div>
</div>
<!-- Links columns -->
<div class="md:col-span-2">
<div class="">
<h3 class="text-white font-medium text-lg mb-3 border-l-2 border-rust pl-3">Resources</h3>
<ul class="space-y-2">
<li>
<a href="/docs/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Documentation</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/tutorials/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Tutorials</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/resources/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Resources</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/plugins/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Plugins</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/showcase/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Showcase</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
</ul>
</div>
</div>
<div class="md:col-span-2">
<div class="">
<h3 class="text-white font-medium text-lg mb-3 border-l-2 border-rust pl-3">About</h3>
<ul class="space-y-2">
<li>
<a href="/team/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Team</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/contributing/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Contributing</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/history/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">History</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="/sponsors/"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="group-hover:text-rust">Sponsors</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
</ul>
</div>
</div>
<div class="md:col-span-3">
<div class="space-y-6">
<div class="">
<h3 class="text-white font-medium text-lg mb-3 border-l-2 border-rust pl-3">Community</h3>
<ul class="space-y-2">
<li>
<a href="https://github.com/betterwebinit/rustyll"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="text-rust"><svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.026 2.747-1.026.546 1.378.202 2.397.1 2.65.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd"/></svg></span>
<span class="group-hover:text-rust">GitHub</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href=""
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="text-rust"><svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24"><path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"></path></svg></span>
<span class="group-hover:text-rust">Discord</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="https://twitter.com/rustylldocs"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="text-rust"><svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24"><path d="M8.29 20.251c7.547 0 11.675-6.253 11.675-11.675 0-.178 0-.355-.012-.53A8.348 8.348 0 0022 5.92a8.19 8.19 0 01-2.357.646 4.118 4.118 0 001.804-2.27 8.224 8.224 0 01-2.605.996 4.107 4.107 0 00-6.993 3.743 11.65 11.65 0 01-8.457-4.287 4.106 4.106 0 001.27 5.477A4.072 4.072 0 012.8 9.713v.052a4.105 4.105 0 003.292 4.022 4.095 4.095 0 01-1.853.07 4.108 4.108 0 003.834 2.85A8.233 8.233 0 012 18.407a11.616 11.616 0 006.29 1.84"></path></svg></span>
<span class="group-hover:text-rust">Twitter</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
<li>
<a href="https://stackoverflow.com/questions/tagged/rustyll"
class="text-gray-300 hover:text-white group transition-all duration-200 flex items-center gap-2 hover:translate-x-1 ">
<span class="text-rust"><svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24"><path d="M15 21h-10v-2h10v2zm6-11.665l-1.621-9.335-1.993.346 1.62 9.335 1.994-.346zm-5.964 6.937l-9.746-.975-.186 2.016 9.755.879.177-1.92zm.538-2.587l-9.276-2.608-.526 1.954 9.306 2.5.496-1.846zm1.204-2.413l-8.297-4.864-1.029 1.743 8.298 4.865 1.028-1.744zm1.866-1.467l-5.339-7.829-1.672 1.14 5.339 7.829 1.672-1.14zm-2.644 4.195v8h-12v-8h-2v10h16v-10h-2z"></path></svg></span>
<span class="group-hover:text-rust">Stack Overflow</span>
<span class="w-0 h-0.5 bg-rust/30 group-hover:w-full transition-all duration-300"></span>
</a>
</li>
</ul>
</div>
<div class="flex flex-col items-center md:items-end mt-8">
<!-- Hosted by GitHub -->
<div class="flex items-center md:justify-end mb-4">
<span class="text-gray-400">Proudly hosted by</span>
<a href="https://github.com"
class="ml-2 opacity-80 hover:opacity-100 transition-all duration-300 transform hover:scale-105 group">
<img src="/img/footer-logo.png"
width="85" height="25"
alt="GitHub • Social coding"
class="h-6 w-auto">
<div class="h-0.5 w-0 bg-gradient-to-r from-transparent via-rust/70 to-transparent group-hover:w-full transition-all duration-300 rounded-full"></div>
</a>
</div>
<!-- Sponsors info -->
<p class="text-gray-400 text-sm mb-4">
Rustyll is funded thanks to its
<a href="https://github.com/betterwebinit/rustyll/sponsors"
class="text-rust hover:text-rust-light transition-all duration-200 relative group">
<span class="relative z-10">sponsors!</span>
<span class="absolute bottom-0 left-0 w-full h-0.5 bg-rust/30 scale-x-0 group-hover:scale-x-100 transition-transform duration-300 origin-left"></span>
</a>
</p>
<!-- Version badge -->
<div class="flex items-center gap-2 mt-4">
<span class="px-3 py-1 bg-rust/10 rounded-full text-rust text-xs border border-rust/30">
v0.1.0
</span>
<a href="https://rustwasm.github.io/docs/book/"
class="px-3 py-1 bg-black/20 rounded-full text-gray-300 text-xs border border-gray-700/30 hover:border-rust/30 hover:text-white transition-all duration-200 flex items-center gap-1">
<svg class="w-3 h-3" fill="currentColor" viewBox="0 0 24 24">
<path d="M12.008 0c-6.63 0-12 5.37-12 12s5.37 12 12 12 12-5.37 12-12-5.37-12-12-12zM2.008 12c0-5.52 4.48-10 10-10 5.52 0 10 4.48 10 10 0 5.52-4.48 10-10 10-5.52 0-10-4.48-10-10z"></path>
<path d="M12.008 16.5c3.038 0 5.5-2.462 5.5-5.5s-2.462-5.5-5.5-5.5-5.5 2.462-5.5 5.5 2.462 5.5 5.5 5.5z"></path>
</svg>
<span>Built with Rust</span>
</a>
</div>
<!-- Back to top button -->
<a href="#"
class="mt-6 inline-flex items-center gap-2 bg-black/30 border border-gray-700/30 rounded-full px-4 py-2 text-gray-300 hover:text-white hover:border-rust/30 transition-all duration-300 transform hover:translate-y-[-3px] group">
<svg class="w-4 h-4 transition-transform duration-300 group-hover:translate-y-[-2px]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 10l7-7m0 0l7 7m-7-7v18"></path>
</svg>
<span>Back to top</span>
</a>
</div>
</div>
</div>
</div>
<!-- Bottom border -->
<div class="border-t border-gray-800 mt-12 pt-6 flex flex-col md:flex-row justify-between items-center">
<div class="flex items-center space-x-2">
<span class="text-gray-500 text-sm">Site Version: 0.1.0</span>
<p class="text-gray-500 text-sm">
Made with
<span class="text-red-500 animate-pulse">❤</span>
by the <a href="https://better-web.org" class="text-white hover:text-rust transition-colors">Better Web</a> community
</p>
</div>
<!-- Scroll indicator -->
<div class="hidden md:block text-gray-600 text-xs transition-opacity duration-300 opacity-70 hover:opacity-100">
<span class="inline-block transform animate-bounce" id="scroll-indicator">↑ Scroll to top</span>
</div>
</div>
</div>
<script>
document.addEventListener('DOMContentLoaded', function() {
const scrollIndicator = document.getElementById('scroll-indicator');
// Only show scroll indicator when page is scrolled down
window.addEventListener('scroll', function() {
if (window.scrollY > 300) {
scrollIndicator.style.opacity = '1';
} else {
scrollIndicator.style.opacity = '0';
}
});
// Smooth scroll to top
document.querySelectorAll('a[href="#"]').forEach(anchor => {
anchor.addEventListener('click', function(e) {
e.preventDefault();
window.scrollTo({
top: 0,
behavior: 'smooth'
});
});
});
});
</script>
</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=""></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="">RustyllConf</a>
<!-- -->
<a href="/showcase/" class="">Showcase</a>
<!-- -->
<a href="/team/" class="">The Rustyll Team</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 1.0.0 Released</h2>
<p></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