Writing Content

undox uses Markdown for all documentation content, with optional YAML front matter for metadata.

Front Matter

Front matter is YAML metadata at the top of your markdown files, enclosed in ---:

---
title: My Page Title
description: A brief description for SEO
---

# Your content starts here

Supported Fields

Custom Fields

You can add any custom fields and access them in templates:

---
title: API Reference
author: Jane Doe
version: 2.0
---

Custom fields are available in templates as page.author, page.version, etc.

Navigation Order

By default, pages are sorted alphabetically by their URL path. You have two options for custom ordering:

Option 1: Filename Prefixes

Use numeric prefixes in filenames:

content/
  guide/
    01-installation.md    # First
    02-configuration.md   # Second
    03-advanced.md        # Third

Option 2: Explicit Nav in Config

Define navigation explicitly in undox.yaml:

sources:
  - name: docs
    path: ./content
    nav:
      - section: Getting Started
        items:
          - quickstart.md
          - installation.md
      - section: Guide
        items:
          - configuration.md
          - content.md

See Configuration for full nav options.

Markdown Features

undox supports standard Markdown plus several extensions:

Tables

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Task Lists

- [x] Completed task
- [ ] Incomplete task

• Completed task
• Incomplete task

Strikethrough

~~deleted text~~

deleted text

Footnotes

Here's a sentence with a footnote[^1].

[^1]: This is the footnote content.

Code Blocks

Fenced code blocks with language identifiers get syntax highlighting:

```rust
fn main() {
    println!("Hello!");
}
```

Renders as:

fn main() {
    println!("Hello!");
}

See Syntax Highlighting for the full list of supported languages.

File Organization

Directory Structure

Your file structure determines your URL structure and navigation:

content/
  index.md              -> /
  getting-started/
    installation.md     -> /getting-started/installation
    quickstart.md       -> /getting-started/quickstart
  guide/
    configuration.md    -> /guide/configuration

Naming Conventions

• Use lowercase filenames with hyphens: getting-started.md
• Directories become navigation sections
• index.md in a directory becomes the section's landing page

Auto-generated Titles

If you don't specify a title in front matter, undox generates one from the filename:

• installation.md → "Installation"
• getting-started.md → "Getting Started"
• api-reference.md → "Api Reference"

Static Files

Non-markdown files (images, PDFs, etc.) are copied to the output directory:

content/
  guide/
    screenshot.png      -> /guide/screenshot.png
    diagram.svg         -> /guide/diagram.svg

Reference them in markdown:

![Screenshot](screenshot.png)

Links

Internal Links

Link to other pages using absolute paths:

See the [Configuration](/guide/configuration) guide.

External Links

Visit [GitHub](https://github.com).