Start from the site program

The fastest way to understand this repository is to read it as two layers:

1. crates/site/ is the real website program.

2. crates/site-core/ is the library that the website program uses.

The docs site is not a separate demo. It is the same application that exercises the framework in this repository.

What lives where

• content/ holds authored markdown content and frontmatter.

• crates/site/ defines collections, routes, and markdown components.

• crates/site-core/ exposes the public site-building API.

• crates/site-assets/ handles asset resolution, transforms, and caching.

• crates/site-diagnostics/ provides the shared diagnostic layer.

Read the code in this order

1. crates/site/src/lib.rs

2. crates/site/src/routes/mod.rs

3. crates/site/src/components.rs

4. crates/site/src/models.rs

5. crates/site/src/main.rs

That order matches how a site author thinks:

• define the site

• define the routes

• define markdown behavior

• define frontmatter types

• wire the CLI

What happens during a build

When you run cargo run -p site -- build, the program:

1. builds a Site

2. loads typed collections from content/

3. expands generated route families

4. renders each route into an artifact

5. writes outputs into dist/

6. records incremental state in .site-cache/

Asset outputs use the same principle. The cache key is based on the source bytes plus a canonical transform description, so unchanged requests can be reused directly.

First small change

Make one safe change first:

1. edit copy in crates/site/src/routes/

2. rebuild the site

3. inspect the generated file in dist/

Then try a content change:

1. add a markdown file under content/blog/

2. rebuild

3. inspect the new route under dist/blog/

Where to go next

• Continue with Your first site.

• Use Work with content images when assets enter the picture.

• Use Override markdown components when you want markdown-generated tags to become Rust functions.

• Use Post-process routes and assets when cleanup belongs after rendering or asset transforms.

• Use Inspect build reports when you need to see what was emitted, skipped, restored, or removed.

• Keep Site-building API open when you need exact method names.

• Read Build-time and render-time contexts when the phase split feels unfamiliar.