Skip to content
Abada Platform

Writing documentation

Pages live under documentation/src/content/docs/ and use Starlight’s file-based routes. Prefer .mdx when importing Starlight components; ordinary Markdown remains suitable for simple prose.

Authoring workflow

Section titled “Authoring workflow”
  1. Identify the authoritative contract or ADR for the behavior.
  2. Update that source and its executable tests when behavior changes.
  3. Update the curated page that explains the behavior.
  4. Add or revise a Mermaid diagram only when relationships or sequence become clearer than prose.
  5. Run the documentation audit, type check and production build.

MDX components

Section titled “MDX components”

Import components from @astrojs/starlight/components at the start of the page:

import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';


<Aside type="caution" title="Contract boundary">
  Explain a risk without hiding it in ordinary prose.
</Aside>

Use components for navigation, steps, tabs and materially important notices. Keep ordinary explanation in Markdown so pages remain easy to review.

Mermaid diagrams

Section titled “Mermaid diagrams”

Use a fenced mermaid block. astro-mermaid renders it during the site build and follows Starlight’s light/dark theme.

```mermaid
flowchart LR
    API --> Command --> PostgreSQL
```

Diagram rules:

  • describe one relationship or sequence per diagram;
  • use stable architectural names rather than transient implementation detail;
  • accompany diagrams with text for accessibility and search;
  • avoid encoding guarantees that are not backed by a contract and test;
  • run the production build so invalid Mermaid syntax fails before review.

Screenshots

Section titled “Screenshots”

Screenshots show readers what to expect; they never prove a claim on their own.

  • Store them under documentation/src/assets/screens/<page>/ as WebP and reference them with a relative Markdown image, so Astro optimizes them: ![What the reader sees](../../../assets/screens/tutorial/03-canvas.webp).
  • Write alt text that says what the image shows, not “screenshot”.
  • Capture Studio at 1440×900 with a device scale factor of 2, from the development profile, and crop to the part the text discusses. Keep files under about 100 KB (cwebp -q 84 -resize 2200 0).
  • Use the development accounts and invented data only — never real customer data, tokens or keys. When a deterministic test model stands in for a real provider, say so on the page.
  • Recapture a screenshot when the screen it shows changes; a stale image is a wrong claim.

Publishing

Section titled “Publishing”

The public site (https://docs.abadaplatform.com) is the Vercel project abada-engine-docs, connected to this repository. Vercel builds it with npm run build (including the link check):

  • a push to main publishes the production site;
  • a push to any other branch builds a protected preview, and only when documentation/ changed (a build that would not change the site is skipped).

Before this connection existed, the project was deployed by hand and stayed on a September build through two releases. After a release, check that the pages the release added answer on the public domain, not only the home page.

Section titled “Links and source-of-truth”

Use site-relative links such as /architecture/runtime/ for curated pages. Link detailed contract sources through the authoritative contracts index. Do not copy entire source documents into this site; summarize their implications so one normative copy remains.

Validation

Section titled “Validation”
Terminal window
cd documentation
npm audit --audit-level=low
npm run check
npm run build

The production build fails when a page links to a page or heading that does not exist (scripts/check-links.mjs checks the built site). CI runs the same commands on every pull request.