Frontmatter

Every MDX file supports YAML frontmatter at the top of the file for page-level configuration.

Example

---
title: Getting Started
short: Start
description: A quick guide to set up your project
order: 2
icon: rectangle-stack
authors:
  - Jane Doe <jane@example.com>
---

# Getting Started

Your content here...

Fields

title

Required. The page title used in navigation, browser tab, and page heading.

title: Installation Guide

short

Optional short label for the sidebar. Use it when the full title is too long for a narrow rail but the page is known by a code its readers already use — a package name, a command, a standard's abbreviation.

title: Space Packet Protocol
short: SPP

The sidebar shows SPP and keeps the full title on the link's tooltip. Headings, breadcrumbs, the browser tab and search all keep using title. Pages that set no short fall back to their title, so this is opt-in per page.

Honoured by the fanfold theme, whose rail is narrow enough to need it, and by its printed header, where the trail reads Protocols / SPP rather than the full title. The default and paper themes ignore it and always show title.

description

Optional meta description for the page. Used in SEO metadata.

description: Step-by-step installation instructions

identifiers

Optional list of extra lines identifying the page — the standard it implements, a package, a command. Each entry is printed as written, so the page decides both the facts and their order.

title: Space Packet Protocol
identifiers:
  - CCSDS 133.0-B-2 * Space Packet Protocol
  - pkg/spp * astro spp

Use it for pages whose readers already know them by something other than a title. A theme cannot work these out for itself, which is why they live in the page.

Honoured by the fanfold theme, which prints them in its header block under the breadcrumb trail. A page that sets none keeps the lines that theme derives on its own — the site name, the section, and the page's path. The default and paper themes ignore the field.

order

Controls the page's position in sidebar navigation. Lower numbers appear first.

order: 1

Decimal ordering is supported for inserting pages between existing ones:

# Page A: order 1
# New page: order 1.5 (appears between A and B)
# Page B: order 2

Pages without an order value appear after ordered pages.

icon

Icon identifier displayed next to the page title in the sidebar.

icon: rectangle-stack

Available icons:

lastModified

Optional date string indicating when the page was last updated.

lastModified: "2026-03-30"

authors

Optional list of the people who wrote the page. Each entry is a plain string — either Name <email> or just a name.

authors:
  - Jane Doe <jane@example.com>
  - Sam Patel

draft

Set draft: true to keep a page out of the site. It is dropped from the navigation tree, so it does not appear in the sidebar, in breadcrumbs, in search, or in the previous/next links.

draft: true

The file stays where it is, so this is the way to leave a page in the repository while it is still being written.

A single author can be written without the list:

authors: Jane Doe <jane@example.com>

Authors appear as a byline on the page, in the page's Article structured data, and on the generated social card. Every author also gets a page at /authors/<slug> listing everything they wrote, and byline names link there. Any url or email an author has is shown on that page rather than in the byline.

A byline shows two authors at most, collapsing the rest into a +N counter that names them on hover. The avatar beside each name is drawn from the author's initials unless the author has an avatar in the authors registry.

Registry keys work here too, and bring the author's bio, avatar, and profile link along with them:

authors: [jane]

Navigation Ordering

Sidebar navigation is determined by:

1. Frontmatter order — Pages sorted by order value (ascending)
2. Decimal values — Use 1, 1.5, 2 for fine-grained positioning
3. Folders — Directories become collapsible groups, auto-named from the folder name (capitalized)
4. No meta.json required — Ordering is entirely frontmatter-based

Example structure

content/
├── index.mdx          # order: 1
├── quickstart.mdx     # order: 2
├── guides/
│   ├── setup.mdx      # order: 1
│   └── advanced.mdx   # order: 2
└── reference/
    ├── cli.mdx        # order: 1
    └── config.mdx     # order: 2

This produces sidebar navigation:

Home (order: 1)
Quickstart (order: 2)
▸ Guides
    Setup (order: 1)
    Advanced (order: 2)
▸ Reference
    CLI (order: 1)
    Config (order: 2)