# The docs site

`apps/docs` is the Andon docs site: an [Astro Starlight](https://starlight.astro.build) 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

```sh
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](https://andon-docs.pages.dev/reference/env.md#the-docs-site)). 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](https://andon-docs.pages.dev/index.md), 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](https://andon-docs.pages.dev/contributing/writing-docs.md) 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.
