The build pipeline

A plasmoid build is a single deterministic pass with no network access. Here’s what happens, in order.

1. Load and validate config

plasmoid.toml is parsed and checked for cross-field invariants — the default locale must be in the locale list, retain must be at least 1, the title must be non-empty. Errors point at the exact offending field so you can fix it fast.

2. Resolve the version

The output version comes from your project’s Cargo.toml (or --version). This determines the /<version>/ output directory. See Versioning.

3. Plan retention

Before rendering, plasmoid decides which versions stay live and which get archived, so the version switcher only lists live versions.

4. Render each locale

For every locale, plasmoid builds the navigation once from the default-locale folder tree, then for each page:

• reads the Markdown source,
• splits and parses frontmatter,
• renders CommonMark to HTML, rewriting intra-docs .md links to clean URLs,
• syntax-highlights code blocks at build time (no client-side highlighter),
• assembles the page chrome (sidebar, switchers, table of contents),
• and writes a complete index.html to the page’s clean-URL directory.

Each page is independent, so the rendering is straightforward and fast.

5. Build the search index

All rendered pages feed a sharded static search index written under /search/. Pages themselves carry no index weight.

6. Apply retention and write the chrome pages

Older versions are zip-archived, the /versions/ index is written, the landing is mounted at /, the stable /docs/ + /latest/ aliases are emitted, and the custom /404.html is rendered.

Properties you can rely on

• Deterministic. The same inputs produce byte-identical output.
• Offline. No network calls at build time.
• Read-only on your content. plasmoid never modifies the Markdown it reads.
• Static and JS-light. Pages are readable with JavaScript disabled; the only scripts are the tiny theme toggle, mobile sidebar, and search.