Writing docs
The site is Astro Starlight in website/. Pages are MDX
files in website/src/content/docs/; the path is the URL.
pnpm docs:dev # http://localhost:4321, live reloadpnpm docs:check # snippets, em-dashes, generated pages (fast; part of pnpm check)pnpm docs:build # the full site, including the API referencepnpm --filter @shoehive/website todo # the stub pages still to writeAdd or finish a page
Section titled “Add or finish a page”- Find the stub:
pnpm --filter @shoehive/website todolists every page whose frontmatter hastodo:. Readers see a "not written yet" banner on those pages. - Write the page and delete the
todo:line. - A new page goes in the folder of its section (
start,tutorials,how-to,concepts,contributing). Tutorials, how-to and concepts appear in the sidebar automatically, insidebar.order; other sections are listed inwebsite/astro.config.mjs.
---title: Spectatorsdescription: Let people watch a table without a seat.sidebar: order: 10---Show code: the one rule
Section titled “Show code: the one rule”Every TypeScript block on the site must compile. There are two ways to show code, and the checks enforce both.
1. Import it from a real file (preferred)
Section titled “1. Import it from a real file (preferred)”Use <Snippet> to show a file, or part of one, from examples/, website/snippets/ or
packages/create-shoehive/. Those files are type-checked (and the examples tested) by
pnpm check.
import Snippet from '../../../components/Snippet.astro';
<Snippet file="examples/tic-tac-toe/src/game.ts" region="game" />fileis relative to the repository root.regionpicks the lines between// #region gameand// #endregion gamein that file (in JSX,{/* #region name */}). Withoutregion, the whole file is shown. Marker lines are never shown, and nested markers are removed.- The title above the code defaults to the path inside the project (
src/game.ts). Settitle="...", ortitle=""for none. - Other props go to Expressive Code, for example
ins={{ range: '6-7' }}to highlight added lines ormark="reject".
When the code is not part of an example, add a file under website/snippets/<topic>/, laid
out like a project (src/game.ts, test/game.test.ts) so relative imports work. It compiles
against the workspace source of shoehive.
2. A short, self-contained fenced block
Section titled “2. A short, self-contained fenced block”A fenced ```ts or ```tsx block is compiled on its own, as one module, with the same
settings. Import what it uses. When it needs values you do not want to show, declare them
above a // ---cut--- line: the check sees them, readers do not.
```tsimport type { AnyGame } from 'shoehive';declare const games: AnyGame[];// ---cut---import { createServer } from 'shoehive/server';
const shoehive = createServer({ games });```On the page, readers see only the last three lines.
Only when a block is deliberately not real TypeScript (wire-format notation, a sketch, an
excerpt that cannot stand alone) add nocheck to its fence: ```ts nocheck. Other
languages (sh, json, mdx) are not checked.
The check
Section titled “The check”pnpm --filter @shoehive/website check:snippetsIt compiles every file under website/snippets/, every ```ts/```tsx block in these
pages and in docs/reference/*.md, and resolves every <Snippet> file and region. Errors
point at the page and line:
website/src/content/docs/how-to/spectators.mdx:24:7: Cannot find name 'tabel'.Pages generated from elsewhere
Section titled “Pages generated from elsewhere”Do not edit these in website/: they are regenerated by pnpm --filter @shoehive/website sync
(run by dev and build) and gitignored.
| Page | Edit |
|---|---|
| Reference: protocol, stores, devtools, benchmarks | docs/reference/*.md |
| Reference: error codes | docs/reference/protocol.md sections 7 and 8, and the source |
| Reference: config options | doc comments on ServerOptions and ClientOptions |
| Reference: changelog | .changeset/*.md, CHANGELOG.md |
| Reference: API | doc comments in packages/shoehive/src (TypeDoc) |
| Contributing: ADRs, RFCs | docs/adr/*.md, docs/rfc/*.md |
Relative links between files in docs/ are rewritten to site URLs, and links to other repo
files point at GitHub.
House style
Section titled “House style”- One idea per page, under 200 lines. Split a long page rather than scrolling.
- Plain, direct English. Short sentences. Address the reader as "you".
- Tutorials start with
<WhatYoullBuild time="..." example="...">, a bulleted list inside (with a blank line after the opening tag and before the closing one). - No emoji. No em-dash characters, anywhere: use a colon, a comma, parentheses or a new
sentence.
pnpm docs:checkfails on them. - Leave a blank line around Markdown inside a component, or Prettier will reflow it.
