Pages and frontmatter

A page is an .mdx file in a content directory. Create the file and it is on the site — there is nothing to register.

Files become URLs

The path under a content directory is the URL:

content/docs/index.mdx              → /docs
content/docs/hello.mdx              → /docs/hello
content/docs/guides/setup.mdx       → /docs/guides/setup
content/docs/guides/index.mdx       → /docs/guides

index.mdx is the page for the folder that holds it. readme.mdx does the same job, which is useful when the folder is also browsed on GitHub.

Frontmatter

Every page opens with a YAML block. title is the only one you always want:

---
title: Installing the CLI
description: Get the command line tool onto your machine.
order: 2
---

The CLI ships as a single binary.

## Requirements

The four fields you will use on nearly every page:

Field	What it does
`title`	The heading above the article, the sidebar label, the browser tab. Always set it
`description`	The line under the heading, plus the meta description and social card
`order`	Where the page sits in the sidebar. Lower first
`draft`	`true` keeps the page out of the site while you write it

There are nine more fields for narrower jobs. See Frontmatter fields for the full list.

Do not repeat the title

Every theme prints title above the article. A page that opens with its own # Installing the CLI shows the same words twice.

---
title: Installing the CLI
---

# Installing the CLI      ← delete this

The CLI ships as a single binary.

Start with your first sentence, and use ## and below for sections. Those are what the table of contents lists — a # in the body never appears there.

Writing MDX

MDX is markdown plus components. Everything you expect from markdown works: headings, lists, tables, links, code fences, block quotes, bold and italic.

On top of that Chronicle gives you callouts, tabs, badges, collapsible sections and Mermaid diagrams. See Components.

Code fences are highlighted by Shiki. Name the language on the fence:

```bash
chronicle dev
```

A fence with no language is rendered as plain text rather than failing, so an ASCII diagram is safe to paste in.

Hiding a page while you write it

Set draft: true:

---
title: Not finished yet
draft: true
---

The file stays where it is, but the page is dropped from the navigation tree — so it is out of the sidebar, breadcrumbs, search, and the previous and next links. This is how you keep unfinished work in the repository.

Reading time and last modified

Reading time is measured from the page body and shown by the themes that have somewhere to put it. You do not set it.

lastModified is a date you set yourself when you want the page to state one:

lastModified: "2026-03-30"

Navigation — ordering pages and naming folders
Components — callouts, tabs, diagrams
Frontmatter fields — all thirteen fields

Writing docs

Guides

Themes

Reference

Deploy and operate