---
search: false
title: Authoring
description: 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](#laying-out-the-folder), [frontmatter fields](#setting-frontmatter-fields), [navigation metadata](#ordering-navigation), and [Markdown support](#writing-markdown).

## Laying out the folder

```text filename="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:

```markdown filename="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.

## Ordering navigation

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

```json filename="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 `---`:

```json filename="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:

```json filename="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`:

```rust filename="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:

````markdown filename="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](/docs/proa-docs/_retired/page-conventions)
  - File routing, frontmatter fields, meta.json navigation, and sidebar icons.
- [Markdown pipeline](/docs/proa-docs/_retired/markdown-pipeline)
  - Markdown lowering, app-owned MDX helpers, code fences, Mermaid, and type tables.
- [Configuration](/docs/proa-docs/configuration)
  - Configure sources, Markdown processing, schemas, search, and output paths.
- [Search](/docs/proa-docs/search)
  - Generate static search manifests and serve search documents.