Writing these docs

This site is Starlight on Astro, in apps/docs. Pages are Markdown; the output is static HTML served by nginx — there is no Node runtime in the image and no database behind it.

Add a page

1. Create a .md file under apps/docs/src/content/docs/<section>/.

2. Give it frontmatter:

   ---
   title: What the page is
   description: One line, used for search results and social cards.
   sidebar:
     order: 3
   ---

3. That is the whole process. The sidebar group is the folder; sidebar.order sets the position inside it.

Add a new section by creating the folder and adding one line to sidebar in apps/docs/astro.config.mjs.

Preview

bun run --cwd apps/docs dev     # :4321, hot reload
bun run --cwd apps/docs build   # static output in apps/docs/dist

Diagrams

Fence a diagram as mermaid and it renders:

```mermaid
flowchart LR
    A[Hold] --> B[PaymentIntent] --> C[Booking]
```

astro-mermaid does this client-side, so the build needs no browser and the image stays small; each diagram type loads its own chunk on demand. The integration must stay before starlight() in astro.config.mjs — it registers the markdown pass Starlight then consumes.

Reach for a diagram when the shape of a flow is the point (a sequence, a state machine, a decision tree). A table is better for anything enumerable.

Typecheck

bun run --cwd apps/docs typecheck runs astro sync && tsc --noEmit, not astro check. The repo is on TypeScript 7, whose native compiler does not yet expose the programmatic API astro check needs. Since the site is Markdown plus one content-config file, tsc covers it. Switch back to astro check when withastro/roadmap#1321 lands.

House style

• Link to the code, do not transcribe it. A path that drifts is worse than no path, so prefer naming the file over pasting its contents.

• Deep design records stay in docs/ next to the code they describe. Link them from here rather than copying them — docs/booking-payments/architecture.md is the example to follow.

• Use asides for anything that has already caused an incident:

  :::danger[Short reason]
  What not to do, and what happens when you do it.
  :::

• Both light and dark are supported here, unlike the app (which is dark-only). The palettes are defined in full in apps/docs/src/styles/tcgkl.css — if you add a colour, add it to both ladders and check it clears WCAG AA against that ladder’s paper.

Shipping

PR into beta, promote to main, same as everything else. On main, the self-hosted runner rebuilds the site and pushes it to the docs-dist branch, which is what Coolify serves. A docs change never touches the web or API containers, and never triggers an image build.