Writing docs

The docs site is generated from markdown: the content/ folder is the database. Anything — a human, a script, an agent — that writes a markdown file into it extends the site. This page is the contract, and every component below is rendered live, so it doubles as the visual QA sheet.

Folder structure#

docs-site/content/
  getting-started/            # category = sidebar group
    _meta.json                # title, order, icon, description
    introduction.md           # page = sidebar item
    quickstart.md
  api-reference/
    _meta.json
    ...

Categories order the sidebar; pages order themselves inside a category. That's the whole hierarchy — two levels, by design. If a category outgrows a flat list, extend build.ts before inventing workarounds in content.

Page frontmatter#

---
title: Your first call          # required — page H1 and sidebar label
description: One-line summary.  # under the H1, on cards, in search
order: 2                        # sort within the category
badge: new                      # optional: new | beta | soon
updated: 2026-08-04             # optional, shown in the meta row
---

Start body content at ## — the H1 comes from frontmatter, and ##/### headings feed the "On this page" rail automatically.

Links#

Internal links are docs-root-relative and extensionless — the build rewrites them for any mount path:

• Internal: [Quickstart](/getting-started/quickstart) → Quickstart
• External: plain URLs, opening in a new tab → the app

Callouts#

Four kinds, same syntax: :::kind Optional title … :::.

Code blocks#

Fences take a language plus an optional title="…"; every block gets a copy button.

client = OpenAI(base_url="https://api.aigridapp.com/v1")  # one-line switch

{ "model": "first-party/llm-gateway", "stream": true }

API endpoint blocks#

A fence with language api, one METHOD /path per line:

Tables#

Build and autogeneration#

cd docs-site && bun run build

The build regenerates every page, the category landings, the home page and search-index.json. Autogenerated content (API references from specs, changelogs from releases) should be emitted as ordinary .md files into the right category — the generator makes no distinction between written and generated pages.