The docs site
apps/docs is the Andon docs site: an Astro Starlight app, themed as “Aquarium”. It
renders the Markdown pages in docs/ as they are, so the pages you maintain here are the site. docs/internal/ stays
off it.
Run it
pnpm --filter @andon/docs dev # http://localhost:4321, live reloadpnpm --filter @andon/docs build # static site in apps/docs/dist, with the Pagefind search indexpnpm --filter @andon/docs preview # serve the build; search only works here, not in devpnpm --filter @andon/docs typecheck # astro checkpnpm exec vitest run --project docs # the loader, links, Copy, Markdown twins, llms.txt and search resultsSet PUBLIC_DOCS_GITHUB_URL and PUBLIC_DOCS_BOARD_URL to show the GitHub link, Edit this page and Open your
board (environment variables). Without them those links are hidden, because the
repository is private and every Andon is self-hosted. Set PUBLIC_DOCS_SITE_URL to the site’s address once it has one,
so /llms.txt and the Markdown twins link pages by full address.
Where things are
| What | Where |
|---|---|
| Every colour, type size, radius and layout width, dark and light | apps/docs/src/styles/tokens.css |
| Starlight mapped onto the tokens, the layout, the content styles | apps/docs/src/styles/theme.css |
| Header, frame, sidebar and phone menu, title row, page actions, “On this page”, footer, theme switch | apps/docs/src/components/ (each replaces the Starlight component of the same name, listed in astro.config.mjs) |
Reading docs/: the index, titles and ledes, links |
apps/docs/src/lib/docs-index.ts, docs-page.ts, docs-loader.ts |
The sidebar, from docs/README.md |
apps/docs/src/lib/docs-sidebar.ts |
| The build’s link check | apps/docs/src/lib/link-check.ts |
| The code block’s header and Copy | apps/docs/src/lib/code-header.ts, code-copy.ts |
| The search dialog | apps/docs/src/components/Search.astro, its results in apps/docs/src/lib/search-results.ts |
| A page’s Markdown twin, and Copy page | apps/docs/src/lib/markdown-twin.ts, page-twin.ts; served by apps/docs/src/pages/[...slug].md.ts |
/llms.txt and /llms-full.txt |
apps/docs/src/lib/llms.ts, llms-site.ts; served from apps/docs/src/pages/ |
| The MDX components | apps/docs/src/components/mdx/ |
| The component gallery and one sample page a template | apps/docs/src/content/docs/ |
| The home, the changelog and the 404 | apps/docs/src/components/Home.astro, Changelog.astro, NotFound.astro, shown through Hero.astro |
| The releases the changelog lists | apps/docs/changelog/, one file a release (its README.md says how to write one) |
Expressive Code’s options (code blocks in Markdown and the <Code> component) |
apps/docs/ec.config.mjs |
| The octopus | docs/logo.png, resized at build |
How a page in docs/ becomes a site page
- Where it is. The site’s sections are the sections of the index, in its order, and each
###heading in a section is a sidebar group. A list item that starts with a link to a page puts that page in the sidebar, under the label the link shows; previous and next follow the same order. An item that starts with text, such as the old addresses, adds nothing. - The front page. The index isn’t shown as written: the site’s front page is the docs home. Its band lists the
index’s sections, each with its line from the index’s opening table (“You want to”) and its first six pages, so a
new section or a reordered one shows there too. The start steps and the install line are written in
Home.astro; the build’s link check fails if a page they link goes. The index stays the front page’s Markdown twin (/index.md), and a link to one of its section or group anchors (README.md#planning-and-organising) lands on that section in the band. - Its address.
docs/guide/board.mdis/guide/board/. The stubs at old addresses render too, at their own addresses. - Its title block. The page’s first
#heading is its title, and the paragraph under it is the lede. Pages carry no frontmatter; don’t add any. - Its template.
docs/reference/pages are reference pages (the wider measure);docs/guide/anddocs/machines/pages are guides; the rest are concept pages. - Its links. Write links for GitHub, as now:
../machines/deploy.md#keep-it-updated. The site points them at the page’s address and keeps the anchor. A link to a file the site doesn’t render (docs/internal/, a deploy recipe, a README beside the code) goes to GitHub whenPUBLIC_DOCS_GITHUB_URLis set, and is plain text when it isn’t. - The link check. The build fails when a link on the site reaches no page, or an anchor that isn’t on its page,
and names each one.
pnpm check:docschecks the Markdown files; this checks what readers get.
A new page in docs/ needs nothing on the site’s side: add it to the index, as Writing docs says, and
it shows up in its section.
Search, Markdown twins and llms.txt
- Search. ⌘K (Ctrl+K),
/or the header’s search field opens it. It reads the Pagefind index the build writes, so it works inpreviewand on the deployed site, not indev. Pagefind indexes each heading on its own, so a result is “Page › Heading” and opens at that heading. Results are grouped by the page’s header section, which the title row hands to Pagefind asdata-pagefind-meta="section:…"; the breadcrumb, page actions and page footer carrydata-pagefind-ignore. The first row opens Claude with the question and the top result’s twin to read: there is no backend to answer it here. - Markdown twins. Every page is also at its address plus
.md(/guide/board/is/guide/board.md, the front page/index.md), as clean Markdown for an agent or a chat. A page fromdocs/is its own Markdown with its links pointed at the other twins. A site page has its components written out: Steps as a numbered list, a Callout as a blockquote that opens with its type in bold (> **Tip:** …), each Tab under its label in bold, a FieldList as a list, a Figure as its caption. Copy page copies the same text; View as Markdown (in the page actions and the page footer) opens it. A component the converter doesn’t know shows only its content, so give a new component a rule inmarkdown-twin.tsand a test. - llms.txt. The build writes
/llms.txt, the site’s title and description and then each section as a list of[Title](twin): description, in the sidebar’s order, and/llms-full.txt, those pages’ twins one after the other. A page outside the sidebar (an old address’s stub) has a twin but isn’t listed.
The changelog and the 404
- The changelog is
/changelog/, newest first, and/changelog/rss.xmlis its feed. Each release is one.mdor.mdxfile inapps/docs/changelog/with its version, date, title, one-line summary, its changes (eachadded,changedorfixed, written for the person using Andon) and, if one page explains it, that page; any body is shown under the changes. The chips filter by kind. Write an entry only for a release that shipped: with none, the page says no release is written up yet. The feed links by full address oncePUBLIC_DOCS_SITE_URLis set. - The 404 names the address that failed and fills its search field with the address’s last part as words
(
/guides/add-machinessearches “add machines”); Enter or a click opens the search with it.
Components
The site’s own pages (.mdx in apps/docs/src/content/docs) can use these by name, imported from
~/components/mdx. The Docs components page on the site shows each one working.
| Component | For |
|---|---|
<Steps> with <Step title="…"> |
A task in order, on guides. The title is the instruction. |
<Callout type="note" title="…"> |
An aside. note (blue), tip (green), warning (amber, needs you), danger (red, failed): the board’s meanings. |
<Tabs label="…"> with <Tab label="…"> |
Alternatives. Arrow keys move between tabs; tabs with the same label switch together across the page. Around code blocks, the tab row is the code’s header. |
<Figure caption="…"> |
A screenshot or illustration in a feature pane. |
<FieldList> with <Field name="…" type="…"> |
A reference page’s fields. |
<Chip kind="added">, <Kbd> |
Inline labels (added, changed, fixed, label, order with n), and keys. |
Every code block, in docs/ pages too, gets a header with its file name (title="…") or language, and Copy. In a
shell block, write commands after $ and output without it: Copy then takes only the commands, without the $ .
<your board>, <name> and your-andon placeholders show in the accent colour.
Previous and next come from the sidebar order, on every page.
The site’s own pages take frontmatter:
title: Mac machinesdescription: Put the Andon agent on a Mac… # shown as the lede under the titletemplate: guide # guide | concept | referencesection: Machines and agents # the breadcrumb after the header sectionrelated: # optional links under "On this page" heading: Related links: - { label: Machine policy, href: /reference/machine-policy/ }A guide does a task in order and gets “Ask about this page”. A concept explains a thing and uses headings, not steps.
A reference page is looked up and gets the wider content measure. List a new site page in SITE_PAGES in
docs-sidebar.ts, or it has no place in the sidebar.
Changing the theme
- Take colours, type, radii and widths only from
tokens.css. The design-token-guard check reads the source for colour literals; a literal colour renders the same as its token, so only the source shows it. - The home, the changelog and the 404 have no sidebar. On a phone their menu sheet holds search, the sections, Open your board and the theme switch, without a page tree.
- The layout changes at 768px (the phone layout and the menu sheet) and 1200px (the “On this page” column; below it, the button under the title).
- Code blocks stay dark in both themes (
--code-bg), so the code theme is one dark theme, and nothing on a code block takes its text colour from the page. - Check a change at 1440, 1180 and 390 wide, in dark and light. The page must never scroll sideways from 360 up; tables and code scroll inside their own pane.
Dependencies
Astro 7.4.2 and later need Node 22.23.4, so apps/docs pins astro 7.4.1 and pnpm-workspace.yaml holds
@astrojs/mdx at 8.1.0 and @astrojs/prism at 4.1.0. Lift all three together once the machines that build Andon run
Node 22.23.4 or later.
