Skip to content

Writing docs

The site is Astro Starlight in website/. Pages are MDX files in website/src/content/docs/; the path is the URL.

Terminal window
pnpm docs:dev # http://localhost:4321, live reload
pnpm docs:check # snippets, em-dashes, generated pages (fast; part of pnpm check)
pnpm docs:build # the full site, including the API reference
pnpm --filter @shoehive/website todo # the stub pages still to write
  1. Find the stub: pnpm --filter @shoehive/website todo lists every page whose frontmatter has todo:. Readers see a "not written yet" banner on those pages.
  2. Write the page and delete the todo: line.
  3. 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, in sidebar.order; other sections are listed in website/astro.config.mjs.
---
title: Spectators
description: Let people watch a table without a seat.
sidebar:
order: 10
---

Every TypeScript block on the site must compile. There are two ways to show code, and the checks enforce both.

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" />
  • file is relative to the repository root.
  • region picks the lines between // #region game and // #endregion game in that file (in JSX, {/* #region name */}). Without region, 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). Set title="...", or title="" for none.
  • Other props go to Expressive Code, for example ins={{ range: '6-7' }} to highlight added lines or mark="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.

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.

```ts
import 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.

Terminal window
pnpm --filter @shoehive/website check:snippets

It 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'.

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.

  • 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:check fails on them.
  • Leave a blank line around Markdown inside a component, or Prettier will reflow it.