Docs

Authoring

Structure documentation files with Markdown, frontmatter, and meta.json navigation.

proa_docs_build compiles a directory of Markdown or configured MDX files into docs routes. This page covers the folder layout, frontmatter fields, navigation metadata, and Markdown support.

Laying out the folder

proa_marketing/src/docs

src/docs/
  index.mdx
  meta.json
  guides/
    index.mdx
    installation.mdx
    meta.json

index.mdx maps to the folder route. For example, src/docs/guides/index.mdx becomes /docs/guides. Frontmatter on each file then controls how that route presents itself.

Setting frontmatter fields

Supported page frontmatter fields:

Field	Type	Purpose
`title`	string	Page title. Falls back to the first heading or file name.
`description`	string	Page description and search metadata.
`icon`	string	Optional sidebar icon name. The generated registry stores it and `DocsNav` emits a `data-icon` hook.
`slug`	string	Override the route slug.
`sidebar_title`	string	Override the title shown in navigation.
`nav_order`	integer	Ordering fallback when no `meta.json` controls the folder.
`hidden`	boolean	Compile the page but omit it from generated nav.
`draft`	boolean	Omit the page unless `include_drafts(true)` is set.
`search`	boolean	Include or exclude the page from search documents.
`toc`	boolean	Store a page-level preference for table-of-contents rendering.
`last_modified`	string	Optional date string for display or plugins.

Example:

src/docs/guides/installation.mdx

---
title: Installation
description: Install Proa crates and create your first page.
sidebar_title: Install
---

# Installation

Frontmatter names one page at a time; meta.json orders the whole folder.

When a folder contains meta.json, its pages array controls ordering and grouping:

src/docs/meta.json

{
  "title": "Start Here",
  "pages": ["index", "installation", "security"]
}

If a pages entry names a folder, proa_docs_build reads that folder's meta.json and emits a nested nav group. If a pages entry names a Markdown file, it emits a page link.

You can also use separator entries in meta.json by prefixing the item with ---:

src/docs/meta.json

{
  "pages": ["index", "---Reference", "api"]
}

Folder meta.json files may include an icon string. The compiler stores the icon on the generated group:

src/docs/reference/meta.json

{
  "title": "Reference",
  "icon": "BookOpen",
  "pages": ["index", "api"]
}

Inside each page, the Markdown parser decides which syntax reaches the rendered HTML.

Writing Markdown

The default parser supports:

headings with generated IDs
tables
strikethrough
task lists
fenced code blocks
links and images
table of contents extraction
search text extraction

The parser escapes inline HTML by default. proa_docs_build recognizes configured type-table requests, but it does not run arbitrary MDX components at runtime. If your site wants helpers such as <Cards> or <Files>, enable them through MdxConfig:

build.rs

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

Good to know: this site stores author-facing files as .mdx and enables MdxConfig::proa(), so supported MDX-like helpers lower to plain Markdown during the build.

The files helper lowers <Files> blocks to the reserved proa-filetree fence:

src/docs/guides/layout.mdx

```proa-filetree
src/
  pages/
    home.rs
  main.rs
```

proa_docs_build renders that fence as a structured file tree. The readable Markdown source survives for .md routes and /llms-full.txt. Routing and sidebar details go one level deeper.

Next steps

Page conventions
- File routing, frontmatter fields, meta.json navigation, and sidebar icons.
Markdown pipeline
- Markdown lowering, app-owned MDX helpers, code fences, Mermaid, and type tables.
Configuration
- Configure sources, Markdown processing, schemas, search, and output paths.
Search
- Generate static search manifests and serve search documents.

Authoring

Laying out the folder

Setting frontmatter fields

Ordering navigation

Writing Markdown

Next steps