scmJS docs

Docs site and screenshots

docs.scmjs.dev is built by npm run build:docs. The guides are the eleven docs/*.md files, split at their ## headings into pages, with the ### beneath as each page's contents. The API reference is generated from the bundled plugin typings, so a doc comment in src/plugins/api.ts is a paragraph on the site.

npm run build:docs                            # → docs-site/ (gitignored)
python3 -m http.server 8000 -d docs-site      # preview it at http://localhost:8000
node scripts/wrap-docs.mjs                    # rewrap the guides' prose at 90 columns
node scripts/wrap-docs.mjs docs/guide.md      # one file
npm run docs:reference                        # the generated tables in triggers.md and chk-format.md

The guides are read on GitHub as well. The site turns a relative link to one of the guides into a link to its page, and anything else in the repository into a link to GitHub. Prose is wrapped at 90 columns; tests/docs.test.ts fails on an unwrapped file, and scripts/wrap-docs.mjs fixes it, leaving code, tables, headings and generated blocks alone. The <!-- generated: … --> blocks in the trigger and CHK references are written from the code by npm run docs:reference; never edit inside them.

Guide screenshots#

The pictures in the guides are docs/images/*.webp, made by scripts/guide-screenshots.mjs. It drives headless Chromium against the dev server, opens the fixture maps, sets up what each picture shows, and writes WebP files. 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              # 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
node scripts/guide-screenshots.mjs --scenes plugin-guide

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

Some scenes have their own needs: