Docs

Config reference

Look up every builder on a proa_docs_build configuration.

proa_docs_build::compile takes one Config value, and every knob in a docs build hangs off it. This page documents that surface: sources and schemas, the Markdown pipeline, search, link validation, and plugins.

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 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::Katex)
    .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>; the bundled syntax set currently excludes TypeScript, TSX, and TOML. 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

Use this when an app runs an additional external MDX lowering pass and wants component-shaped inline HTML preserved for that pass.

TypeScript docgen is one such external pass.

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. That avoids silently publishing unresolved type API placeholders.

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() warns on broken internal links and hashes. LinkValidation::strict() turns those warnings into build errors.

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

• Configuration
  • Wire these builders into a production build.rs.
• 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.