Editing the docs

These docs are an Astro Starlight site that lives in docs-site/. To fix a typo or add a page you edit one Markdown file and open a PR — the sidebar, breadcrumbs, search index, and styling all regenerate from the build. There is no separate navigation file to hand-edit.

Edit an existing page

1. Find the page under docs-site/src/content/docs/ — the URL maps to the path (/operations/architecture/ → src/content/docs/operations/architecture.md).
2. Edit the Markdown. The first --- block is frontmatter (title, description, optional lastUpdated).
3. Open a PR. That's the whole flow.

Add a new page

Drop a new .md file under the right folder with frontmatter:

---
title: My new page
description: One sentence for search results and social cards.
---

Body content in Markdown.

It appears at the matching URL automatically. To place it in the sidebar in a specific spot, add it to the sidebar config in docs-site/astro.config.mjs (operations and data-source pages are listed there in order; other folders can auto-generate).

Conventions

• Stable anchors. To pin a heading's id (so deep-links survive edits), use ## Heading {#my-id}. Without it, the id is auto-slugged from the heading text.
• Per-source pages link out. A source page keeps the Josh-specific detail — schema, chunker, citation IDs, status, and probe findings — and links to the upstream API docs for endpoint shapes and field definitions rather than reproducing them.
• Fence everything code-like. Wrap XML, SQL, JSON, and shell in fenced code blocks so the build doesn't try to parse <tags> or {braces}.

The Spec section is different

/spec/ is not Markdown. It is generated from docs/spec/data/*.yaml by bin/build-spec.py and served verbatim. To change a spec, edit its YAML (or use the in-page editor) and regenerate — see the spec workflow. The docs build mirrors the generated spec HTML into the site automatically.

Run it locally

cd docs-site
npm install          # first time
npm run dev          # local preview with live reload
npm run build        # production build into dist/
npm run linkcheck    # validate internal links + anchors (after a build)

The build needs Node ≥ 22.12 (pinned in docs-site/.node-version). npm run dev/build run a prebuild step that regenerates the spec HTML and mirrors it (plus the design tokens) into the site.