Docs
Proa Docs
A docs framework for Proa sites, compiled at build time.
Proa Docs is a docs framework for Proa sites, largely inspired by fumadocs and nextra from JavaScript-land.
Write Markdown, get a documentation site: file-routed pages, a generated sidebar, syntax highlighting, search, a table of contents, and thirteen authoring components.
- Quickstart: Two crates, a build script, one route.
- Code block: Highlighting, filenames, line marks, and copy controls.
Everything happens at build time
This is the difference that matters. Markdown is parsed, highlighted, and lowered to escaped static HTML during build.rs, then emitted as a static Rust registry your binary includes.
No parser ships to the reader. No syntax highlighter, no math renderer, no client-side router. A docs page is bytes that were computed once.
The practical consequences:
- Syntax highlighting costs nothing at runtime. Syntect runs in your build; tokens carry semantic
hl-*classes your stylesheet colours. - Math is MathML. Where most sites ship KaTeX and a font, Proa compiles TeX during the build and ships markup the browser already renders.
- Tabs, accordions, and the code explorer need no JavaScript. They lower to CSS-only patterns.
- Every page has HTML and Markdown representations generated from the same source, so browsers, command-line clients, retrieval pipelines, and agents can access the content without a second authoring pipeline.
Two crates, two jobs
| Crate | Runs | Owns |
|---|---|---|
proa_docs_build | build.rs | Parsing, frontmatter schemas, the Markdown pipeline, components, search index, link validation |
proa_docs | request time | The static data model, render primitives, and the default theme |
proa_docs is deliberately small. It holds the compiled registry and renders a shell around generated article HTML. It also ships the CSS and JavaScript that make the components work, so a site that links DocsAssets from its head is styled on a fresh install.
You can also ignore the default theme entirely and write your own against the styling contract. That is the headless path, and it is a supported one.
What runs in the browser
The article HTML, syntax highlighting, and MathML are generated at build time. Tabs, accordions, and code explorers use CSS. Copy controls need the optional default script; search UI and Mermaid rendering need their own integration. The runtime still selects a page, renders its shell, and serves the response. See Customizing the layout for composing a themed shell and Mermaid for its renderer requirement.
Next
- Pages and routes: How files become routes.
- Navigation: Order the sidebar with meta.json.
- Rendering pages: Put a docs site inside your Proa app.
- Configuration: Every build option in one reference.