OnlyWorlds docs

The source of onlyworlds.github.io: the OnlyWorlds schema, API, SDKs and AI tools. Built with Starlight and deployed to GitHub Pages by .github/workflows/pages.yml.

The Jekyll site this replaced is kept whole on the jekyll branch and the jekyll-final tag.

Work on it

npm ci
npm run build     # gen_sdk_ref, gen_errors, astro build, then scripts/postbuild.mjs
npm run verify    # the workflows parse (verify-workflows.mjs), then the URL gate (verify-urls.mjs) on dist/
node scripts/serve.mjs   # dist/ on http://localhost:4321/, resolved the way GitHub Pages resolves it

Pages are Markdown in src/content/docs/, at the URL they are served from. The sidebar (in astro.config.mjs) is independent of the folders.

Deploys. pages.yml runs on every push to main and whenever schema-dist publishes (its publish step runs gh workflow run pages.yml -R OnlyWorlds/onlyworlds.github.io). A 4-hourly schedule is only a fallback: GitHub runs scheduled workflows late or not at all. Nothing uploads unless npm run verify passes. Push and manual deploys are tagged docs-live-<date>-<run>; to roll back, run the workflow on an earlier tag. An outside check watches the live site and notices if the workflow is disabled (GitHub does that after 60 days without activity) or the site falls behind schema-dist.

Run npm run verify before you push: a workflow file that doesn't parse never runs, and GitHub shows no failed check, only none.

Keeping it true

Docs follow what ships, the same hour, and a weekly sweep catches the rest: node scripts/sweep.mjs, then the reading list and the terms in SWEEP.md.

Old URLs are part of the contract

The API's error responses link to /api/errors#<code>, the LLM guide lives at /assets/ow_llm_guide.txt, and tools, READMEs and AI chats link to old paths. contract/urls.tsv lists every one, with where it is linked from:

• load-bearing rows must answer 200 with the real page, on this host. Never a redirect stub: agents read the stub, not its target.
• floor rows are the error codes keel links to; each must be an id on /api/errors/.
• page rows are old pages nothing outside links to; a stub redirect is enough if one moves.

Two checks read that file: npm run verify on every build (CI and the deploy), and the outside check on the live site. A page keeps its path; to move one that the contract lists, change the contract first.

build.format: 'file' writes page.html, which Pages serves as both /page and /page.html (the old site's two forms). scripts/postbuild.mjs moves section pages (<dir>/index.md) back to <dir>/index.html, so /docs/x keeps its same-host 301 to /docs/x/. A directory that holds pages but none of its own (/docs, /api, /docs/development/api) gets a copy of the page named for it in DIR_INDEX, and a new one fails the build until it is named. Every other page is a file, so /page/ answers the 404 page, which in a browser sends it on to /page once.

Element pages

The field tables on the 22 element pages are generated by scripts/gen_elements.py from schema-dist, through schema-dist's own walk (imported from the checkout after it is verified against its MANIFEST.json, never copied). Hand-written prose stays above the marker line; everything below it is rewritten. Every deploy runs the generator, so the site follows the schema without a commit here.

python scripts/gen_elements.py --dist ../schema-dist          # rewrite
python scripts/gen_elements.py --dist ../schema-dist --check  # exit 1 if a page is behind

Other generated parts

• The errors page's summary table and the contract's floor rows come from keel's own list of error codes (Error.x-ow-error-codes in its OpenAPI), vendored as contract/error-codes.json. scripts/gen_errors.mjs runs in every build. It fails when a public code has no ### <code> section, when a section isn't a public code, or when the Upload Host Errors table disagrees with the host rows. The sections themselves are hand-written. --refresh re-reads the live list; --live compares the snapshot with it (CI and the deploy warn on a difference).
• The TypeScript page's reference comes from the pinned @onlyworlds/sdk (a dev dependency): scripts/gen_sdk_ref.mjs reads its types with the TypeScript compiler. Bump the pin after an SDK release to move the reference.

Contributing

Open an issue or a pull request. The field descriptions on the element pages are the schema's own text, so raise a change to one on the standard's repository rather than here; the next deploy picks it up.

License

The code is MIT (LICENSE). The documentation's text is CC BY 4.0 (LICENSE-CONTENT): share and adapt it with credit.