Skip to content
AndonDocs
GitHub
Change Andon

The docs site

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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

shell
pnpm --filter @andon/docs dev # http://localhost:4321, live reload
pnpm --filter @andon/docs build # static site in apps/docs/dist, with the Pagefind search index
pnpm --filter @andon/docs preview # serve the build; search only works here, not in dev
pnpm --filter @andon/docs typecheck # astro check
pnpm exec vitest run --project docs # the loader, links, Copy, Markdown twins, llms.txt and search results

Set 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.md is /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/ and docs/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 when PUBLIC_DOCS_GITHUB_URL is 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:docs checks 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 in preview and on the deployed site, not in dev. 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 as data-pagefind-meta="section:…"; the breadcrumb, page actions and page footer carry data-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 from docs/ 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 in markdown-twin.ts and 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.xml is its feed. Each release is one .md or .mdx file in apps/docs/changelog/ with its version, date, title, one-line summary, its changes (each added, changed or fixed, 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 once PUBLIC_DOCS_SITE_URL is set.
  • The 404 names the address that failed and fills its search field with the address’s last part as words (/guides/add-machines searches “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:

YAML
title: Mac machines
description: Put the Andon agent on a Mac… # shown as the lede under the title
template: guide # guide | concept | reference
section: Machines and agents # the breadcrumb after the header section
related: # 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.