Guides

Writing docs

Add a page to this engine, and the components you can use in one.

The docs surface reads MDX off the filesystem. There is no database and no build step beyond next build.

Add a page

Create src/content/docs/<section>/<page>.mdx:

Mdx

---
title: Deploying
summary: Ship the app to production.
order: 4
updatedAt: "2026-08-27"
---

Body copy starts here.

The route follows the path: that file serves /docs/guides/deploying. The sidebar, the search index, the previous and next links and generateStaticParams all derive from the filesystem, so nothing else needs updating. Frontmatter fields:

title — heading and sidebar label. Falls back to the filename.
summary — shown under the title, in the section index and in search.
order — position within the section. Pages without one sort last.
updatedAt — ISO date, rendered at the foot of the page.

Add a section

Create the directory, then give it a label in src/content/docs/nav.json:

Json

{
  "sections": [
    { "dir": "guides", "label": "Guides", "description": "Recipes." }
  ]
}

Sections missing from nav.json still render — they sort alphabetically after the listed ones and take a label derived from the directory name. A malformed nav.json falls back to that same behaviour rather than taking the docs down.

Components in MDX

Markdown maps onto Once UI: headings become anchored HeadingLinks that the table of contents reads, fenced code becomes a CodeBlock with a copy button, and lists, quotes and images become their Once UI equivalents. A registered set of components is available directly in the body — among them Accordion, AccordionGroup, Card, Grid, Row, Column, Feedback, Table, Media and Button. The registry lives in src/components/Mdx.tsx; anything not registered there is not available, which is what keeps documentation from drifting into bespoke layout.

Tables

Markdown table syntax is not enabled. Use the Table component for tabular data, or a list when the data is really a list.

Last updated August 27, 2026

Edit this page on GitHub