Docs

Configuration

Set up build.rs, then every option in one place.

One Config value drives the whole build. Start with the minimal script; the reference below covers every builder.

Proa Docs compiles a Markdown tree in build.rs, so a finished site ships as generated Rust with no runtime parser. This page covers Cargo setup, a production build script, schemas, and the generated output.

Adding the Cargo dependencies

Add the build crate to build-dependencies and the runtime crate to normal dependencies.

[build-dependencies]
proa_docs_build = { git = "https://github.com/Proa-Labs/proa.git" }

[dependencies]
proa_docs = { git = "https://github.com/Proa-Labs/proa.git", features = ["axum"] }

These git dependencies work from a standalone application checkout. Repository contributors can keep using the workspace's in-repository path dependencies through the root workspace manifest.

The include_docs!("docs") argument must match the source out_dir_name("docs").

With both crates in place, the build script decides what the compiler produces.

Writing a production build script

Most apps start from this shape. It turns on code highlighting and search artifacts, and it runs strict link validation in CI. It also prints cargo:rerun-if-changed for the docs directory.

use std::{env, path::PathBuf};

fn main() {
    let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
    let docs_dir = manifest_dir.join("src/docs");

    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed={}", docs_dir.display());

    let markdown = proa_docs_build::MarkdownPipeline::default()
        .code_highlighting(proa_docs_build::CodeHighlight::new())
        .mdx(proa_docs_build::MdxConfig::proa())
        .mermaid(proa_docs_build::MermaidConfig::new());

    let link_validation = if env::var_os("CI").is_some() {
        proa_docs_build::LinkValidation::strict()
    } else {
        proa_docs_build::LinkValidation::new()
    };

    let docs = proa_docs_build::DocsSource::new(docs_dir)
        .out_dir_name("docs")
        .base_path("/docs")
        .site_name("My Docs")
        .markdown(markdown)
        .search(proa_docs_build::SearchConfig::orama_client())
        .link_validation(link_validation)
        .include_drafts(false);

    proa_docs_build::compile(proa_docs_build::Config::new().source(docs));
}

Call compile(config) in normal apps. You can call try_compile(config) instead when your build script adds custom diagnostics before panicking.

That call writes a registry, which stays inert until your app includes it.

Including the registry at runtime

Include the generated registry in your app shell or docs route module.

static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");

The registry contains:

Use DOCS.page_for_path(path) for request routing. Use DOCS.find_page(slug) when you already have a slug.

Both lookups lean on base_path, one of the defaults the next section lists.

What defaults does DocsSource start with?

DocsSource::new(root) starts with production-oriented defaults:

The compiler normalizes base_path. Empty input and / become /; other values get a leading slash and no trailing slash.

Each source carries its own copy of these settings, so one build can compile several.

Compiling multiple sources

Compile docs, blog posts, changelogs, or API references in one build by adding more sources. Each source gets its own generated registry.

let markdown = proa_docs_build::MarkdownPipeline::default()
    .code_highlighting(proa_docs_build::CodeHighlight::new())
    .mdx(proa_docs_build::MdxConfig::proa());

let config = proa_docs_build::Config::new()
    .source(
        proa_docs_build::DocsSource::new("src/docs")
            .out_dir_name("docs")
            .base_path("/docs")
            .site_name("Docs")
            .markdown(markdown.clone()),
    )
    .source(
        proa_docs_build::DocsSource::new("src/blog")
            .out_dir_name("blog")
            .base_path("/blog")
            .site_name("Blog")
            .markdown(markdown),
    );

proa_docs_build::compile(config);

Runtime includes stay separate:

static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");
static BLOG: proa_docs::Docs = proa_docs::include_docs!("blog");

Sources also differ in the frontmatter they demand, which is what schemas describe.

Validating frontmatter with schemas

Use schemas when a collection needs required or typed metadata.

let page_schema = proa_docs_build::PageSchema::new()
    .required_string("title")
    .optional_string("description")
    .bool_with_default("draft", false)
    .date("last_modified");

let meta_schema = proa_docs_build::MetaSchema::new()
    .optional_string("title")
    .optional_string("icon");

let docs = proa_docs_build::DocsSource::new("src/docs")
    .schema(page_schema)
    .meta_schema(meta_schema);

A schema allows unknown frontmatter fields. App-owned metadata passes through, and the compiler still checks the fields you declared.

Once validation passes, the compiler writes its artifacts under $OUT_DIR.

Reading the generated output

The compiler writes generated Rust, article HTML, Markdown source copies, table-of-contents data, pager links, and search JSON under $OUT_DIR/proa_docs/<out_dir_name>/. For out_dir_name("docs"), the tree looks like this:

include_docs!("docs") includes docs.generated.rs. The Markdown copies power .md routes and copy-for-LLM workflows. The compiler emits the search files when you enable search.

Check those artifacts once, then run the list below before every deploy.

Shipping a docs site

Before publishing a docs site:

Next steps

• Runtime
  • Include the registry, serve static artifacts, and render your own shell.
• Markdown pipeline
  • Follow a page through MDX lowering, fences, Mermaid, and search text.
• Link validation
  • Fail the build on broken internal routes and heading hashes.

Reference

Config

Config is the top-level build object that you pass to proa_docs_build::compile(config).

let config = proa_docs_build::Config::new()
    .source(docs_source)
    .source(blog_source)
    .plugin(proa_docs_build::plugins::last_modified());

Sources do the compiling, and DocsSource is the one that produces docs pages.

DocsSource

DocsSource::new(root) compiles one documentation tree.

The compiler normalizes base_path. Empty input and / become /; all other values get a leading slash and no trailing slash.

Two of those settings, schema and meta_schema, describe the metadata a tree must carry.

PageSchema

PageSchema validates frontmatter fields that your collection requires:

let schema = proa_docs_build::PageSchema::new()
    .required_string("title")
    .optional_string("description")
    .bool_with_default("draft", false)
    .date("last_modified");

Schema validation checks the fields you configure. The compiler allows unknown fields, so app-specific frontmatter passes through.

Directory metadata lives in meta.json files, and MetaSchema checks those.

MetaSchema

MetaSchema supports optional string validation:

let meta_schema = proa_docs_build::MetaSchema::new()
    .optional_string("title")
    .optional_string("icon");

Use it when a site wants typed checks for custom meta.json metadata.

Past validation, Postprocess decides which side artifacts the build keeps.

Postprocess

Postprocess controls generated side artifacts.

The current compiler always produces all three artifacts; these flags are configuration surface for opting out in a future release.

The largest artifact, page HTML, comes out of the Markdown pipeline.

MarkdownPipeline

MarkdownPipeline controls the Markdown compiler:

let markdown = proa_docs_build::MarkdownPipeline::default()
    .code_highlighting(proa_docs_build::CodeHighlight::new())
    .mdx(proa_docs_build::MdxConfig::proa())
    .mermaid(proa_docs_build::MermaidConfig::new())
    .math(proa_docs_build::MathMode::MathMl)
    .component_indexing(
        proa_docs_build::ComponentIndexing::new()
            .preserve(["Cards", "Files"])
            .children_only_default(true),
    )
    .typescript(proa_docs_build::TypeScriptDocgen::new().command("pnpm docgen"));

Each builder gets its own section below, starting with CodeHighlight.

CodeHighlight

With highlighting on, Syntect maps recognized-language tokens to stable semantic hl-* classes during the docs build. The site supplies the class colors, including light and dark themes. Unknown languages fall back to escaped <pre><code>. TypeScript, TSX, and JSX fences highlight through the bundled JavaScript grammar; TOML is not in the bundled syntax set and falls back to plain code. Every highlight-enabled block carries data-code-highlight="syntect", safe fallback blocks included, so client-side highlighters can skip them.

MathMode handles the other class of typeset content.

MathMode

MDX lowering, unlike math handling, rewrites the source before the parser sees it.

MdxConfig

MdxConfig is an optional build-time lowering pass for .mdx files. It does not execute arbitrary MDX or JavaScript. It rewrites a small configured helper subset to plain Markdown before the normal Markdown compiler runs.

let markdown = proa_docs_build::MarkdownPipeline::default()
    .mdx(proa_docs_build::MdxConfig::proa());

The pass writes its processed Markdown into DocPage::markdown, which the .md routes serve.

Images take enough options to warrant their own config.

MdxImageConfig

MdxImageConfig controls simple image lowering:

let images = proa_docs_build::MdxImageConfig::new()
    .default_alt("Image")
    .rewrite_prefix("/images/", "/static/images/");

Diagrams survive lowering as mermaid fences, which MermaidConfig picks up.

MermaidConfig

MermaidConfig::new() enables Mermaid support.

The renderer accepts Client, StaticSvg, and Custom. The current compiler emits client-rendered placeholders for Mermaid fences when you enable them.

Components the lowerer leaves alone can still reach an app-level pass through ComponentIndexing.

ComponentIndexing

This is reserved configuration surface: the builder is accepted and stored, but no compile step reads preserve or children_only_default yet. Inline HTML that is not a recognized container tag or type-table directive is always escaped.

TypeScriptDocgen

TypeScriptDocgen::new() enables type-table requests. The default component name is auto-type-table.

Compilation fails when Markdown requests type tables and you enable TypeScript docgen without a command. With a command set, requests still ship as pending placeholders; resolution is not implemented yet.

With the pages compiled, SearchConfig decides how readers find them.

SearchConfig

Every enabled mode emits a search manifest and documents JSON today. Your app decides whether to load them on the client, serve them through an API, or feed another index.

LinkValidation guards the other half of navigation: the links themselves.

LinkValidation

LinkValidation::default() uses Warn mode, which compile does not act on: no validation runs and nothing is printed. LinkValidation::strict() (Error mode) validates during compile and fails the build, printing each broken link first. To get a report without failing, call validate_links yourself.

See Link validation for examples.

Collections reuse the same source shape for data that is not a docs page.

CollectionSource

CollectionSource is available for future collection compilation.

Plugins are the last extension point on Config.

Plugins

proa_docs_build exposes two plugin constructors today:

The plugin API stays small while docs compilation stabilizes.

Next steps

• Markdown pipeline
  • Follow a page through MDX lowering, fences, Mermaid, and search text.
• Link validation
  • Fail the build on broken internal routes and heading hashes.
• Runtime
  • Include the generated registry and render it from your app.

Related

Quickstart · Rendering pages · Search · Link validation