---
title: Proa Docs
description: A docs framework for Proa sites, compiled at build time.
---

Proa Docs is a docs framework for Proa sites, largely inspired by [fumadocs](https://www.fumadocs.dev/) and [nextra](https://nextra.site/) 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](/docs/proa-docs/quickstart): Two crates, a build script, one route.
- [Code block](/docs/proa-docs/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](/docs/proa-docs/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](/docs/proa-docs/customizing) for composing a themed
shell and [Mermaid](/docs/proa-docs/mermaid) for its renderer requirement.

## Next


- [Pages and routes](/docs/proa-docs/pages-and-routes): How files become routes.
- [Navigation](/docs/proa-docs/navigation): Order the sidebar with meta.json.
- [Rendering pages](/docs/proa-docs/runtime): Put a docs site inside your Proa app.
- [Configuration](/docs/proa-docs/configuration): Every build option in one reference.