RSTRust-First Site ToolkitA Rust-first static site generator with typed collections, explicit routes, and a format-agnostic asset pipeline.

Learn by building

Your first site

Build the smallest complete site shape with typed content, explicit routes, and markdown rendering.

Tutorials

Build the smallest useful site

This tutorial walks through the smallest complete shape that still reflects the framework's design:

  1. markdown content under content/

  2. a Rust site program under crates/site/

  3. a build that writes static files into dist/

If you have not looked around the repository yet, read Getting started first.

1. Add content

Create a file under content/blog/:

---
title: Hello world
date: 2026-03-28
tags:
  - intro
---

This is my first post.

This gives the site one typed content entry to load from the blog collection.

2. Define the site in Rust

At its smallest, the site definition looks like this:

use maud::html;
use serde::Deserialize;
use site_core::{Artifact, Site};

#[derive(Clone, Debug, Deserialize)]
struct BlogPost {
    title: String,
    date: String,
}

fn build_site() -> site_core::Result<Site> {
    Site::builder()
        .content_dir("content")
        .cache_dir(".site-cache")
        .collection::<BlogPost>("blog")
        .page("/", |ctx| {
            let posts = ctx.collection::<BlogPost>("blog")?;
            Ok(Artifact::Html(html! {
                html {
                    body {
                        h1 { "Home" }
                        p { (format!("{} posts loaded", posts.len())) }
                    }
                }
            }))
        })
        .collection_page::<BlogPost, _>("blog", "/blog/{slug}/", |ctx, entry| {
            let body = ctx.render_content(entry)?;
            Ok(Artifact::Html(html! {
                html {
                    body {
                        article {
                            h1 { (&entry.frontmatter.title) }
                            (body)
                        }
                    }
                }
            }))
        })
        .build()
}

There is no template DSL hiding the site structure. Collections, routes, and render behavior are ordinary Rust.

3. Build the site

Run:

cargo run -p site -- build

That command loads content, expands routes, renders artifacts, writes dist/, and updates .site-cache/.

4. Inspect the outputs

After the build:

  1. open dist/index.html

  2. open dist/blog/<slug>/index.html

  3. inspect dist/assets/ if the content referenced local media

On a second build, unchanged routes and asset transforms should be skipped or restored from cache.

5. Add the first conveniences

From here, most sites usually add three things:

  1. custom markdown components

  2. non-HTML routes such as sitemap.xml

  3. asset transforms for authored images

Those all stay explicit in Rust too.

Next steps