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-09-09             # optional, shown in the meta row
---

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

Documenting the product honestly#

These docs describe the product as it exists today. Every endpoint, error code, field and limit on a page must trace to the running implementation — for the current release that means the contract documents in backend/foundation/ (API-CONTRACT.md, PRODUCT-RUNTIME.md, SANDBOX-RUNTIME.md) or the Go code itself. If you cannot verify a claim, leave it out.

Planned-but-unbuilt features get marked, never documented as if they work:

• set badge: soon in the frontmatter, and
• open the page with a :::warning callout stating the feature is not yet available, and
• describe the planned shape only — no step-by-step instructions that imply it works today.

A page about a capability that has not rolled out yet uses this convention.

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": "openai/gpt-oss-20b", "stream": true }

Use real identifiers in examples — the model id above is one a project can actually be assigned, and API keys really do look like aig_…. Invented placeholders teach the reader a product that does not exist.

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.