The documentation site

docs.scmjs.dev is npm run build:docs, deployed by the docs job on a tag so the site, the hosted editor and the installers are one version. It has two halves. The guides are docs/*.md, split at their ## headings into pages with the ### beneath as each page's contents; nothing on the site is prose a generator wrote, and these files stay where it is maintained. The reference is generated from the bundled plugin typings, so a doc comment in src/plugins/api.ts is a paragraph on the site and a member with none shows as a bare signature.

npm run build:docs                                  # → docs-site/ (gitignored)
node scripts/build-docs.mjs --out /some/dir

The guides are written to be read on GitHub as well; the site's link rewriter turns a relative link to one of the eight documents into a page and anything else in the repository into a link back to GitHub, and tests/docs.test.ts checks every link and picture.

Guide screenshots#

The pictures in the user guide are docs/images/*.webp, made by scripts/guide-screenshots.mjs against the dev server and the fixture maps: it drives a headless Chromium through Playwright, opens the maps, paints and places what each picture shows, and writes WebP files, lossless for a dialog and lossy for a window of terrain. Re-run it after a change to the chrome and commit the pictures that changed.

npm run dev                                   # in one terminal
npm i --no-save playwright sharp              # not dependencies: only this script needs them
npx playwright install chromium               # once
node scripts/guide-screenshots.mjs            # → docs/images/
node scripts/guide-screenshots.mjs --only units,fog

It needs the game data extracted and Big Game Hunters, Binary Burghs, Crescent Moon and Ground Zero from the game's own Maps folder in fixtures/maps/. Never commit a picture that shows anything but the editor.

The plugin guide's pictures are the scene plugin-guide (node scripts/guide-screenshots.mjs --scenes plugin-guide). It needs the game data but no fixture map: it makes its own map through the plugin API, and each picture is one of the examples in docs/plugins.md, run in the API Playground. An example the scene cannot find in the guide stops it, so changing an example that has a picture means re-running the scene.

The API Playground pictures (--scenes api-playground) install that plugin for their scene, since it is not a default: from its repository, or from a local build with --playground http://localhost:3000/ while you work on it. The scene opens Crescent Moon, runs the Place units in a ring example and takes the hover over api.document.edit.

The scmjs.dev pictures — the Account dialog, My Maps, the AI dialogs and the assistant — are taken against a stand-in for the service, scripts/lib/guide-scmjs-mock.mjs, which the script starts on port 8765 and points the plugin at through its stored settings: one signed-in account with a ledger, real map storage for what the scene uploads, and recipe answers written in advance for the fixture maps. Those pictures show the editor's chrome around example content, not a model's output; when a dialog changes, change the scene, and when a canned answer no longer fits the map it is written for, change the mock.

The shared-map pictures use the same stand-in, which also runs the rooms and their WebSocket the way the service does: the scene shares Big Game Hunters from one editor and joins it from a second, signed-out one, so the marines that editor places reach the first as real changes. A third person nobody drives is seated by the stand-in, and the others' pointers are pinned to set places, since a headless browser has no mouse to follow. The link in the Share dialog is rewritten to the hosted editor's address before the picture.