Docs

Page conventions

File routing, frontmatter fields, meta.json navigation, and sidebar icons in Proa Docs.

proa_docs_build compiles a directory of Markdown files into a static Docs registry. The compiler keeps the model deliberately small: files define routes, frontmatter defines page metadata, and meta.json defines navigation.

File Routes

Routes come from file paths under the docs source root:

index.mdx maps to the folder route. Other file stems map to the final path segment.

Frontmatter

Supported page fields:

Example:

---
title: Route Handlers
description: Build JSON endpoints, form handlers, webhooks, and health checks.
sidebar_title: Handlers
icon: Route
---

# Route Handlers

Navigation Metadata

Each folder can include a meta.json file:

{
  "title": "Framework",
  "icon": "Route",
  "root": true,
  "pages": [
    "---Start Here---",
    "index",
    "---Request lifecycle---",
    "routing",
    "route-handlers",
    "responses"
  ]
}

The compiler supports these pages entry types:

If a pages entry names a folder, the folder must contain meta.json. If it names a page, the compiler resolves .md, .mdx, or index by convention.

Set "root": true on a child folder to make it an independent navigation root. The generated section menu uses that folder's title and icon, links to its first page, and shows only its pages while one of its pages is active. Root folders appear in the section menu, not as groups inside another root's sidebar. The source-level meta.json remains the default root, and its non-root separators, pages, and groups stay visible on pages outside a child root.

Icons

Pages can set icon in frontmatter. Folders can set icon in meta.json.

The generated runtime stores the value in two places:

• Frontmatter.icon on the page.
• NavItem.icon on the generated nav item.

DocsNav renders a .proa-docs-nav-icon span with data-icon="<name>". The default runtime includes a small inline SVG map for common names such as BookOpen, Cpu, FileText, Settings, Brain, Layers, ArrowRightLeft, Route, Terminal, and Zap. Unknown names fall back to a file icon, and applications can still target the data-icon hook for custom styling or replacement.

Current Differences From Fumadocs

Proa Docs intentionally supports a smaller navigation model today:

This keeps generated Rust predictable and avoids coupling docs compilation to a specific frontend icon package.