Writing the docs
The site is static HTML written to dist/docs by tools/docs/build.mjs (pnpm docs). It needs no server and no network: open index.html, or pnpm serve 8080 dist/docs.
Guides#
A guide is a Markdown file in docs/. Its folder shows in the URL, its front matter places it:
---
title: Gameplay packages
group: Gameplay # the navigation group; order of groups is in docs/packages.json
order: 20 # position inside the group
summary: One line for search results and cards.
---The renderer supports headings (levels 2 and 3 make the page's table of contents), paragraphs, bold, italic, code, links, nested lists, tables, quotes and fenced code blocks.
Links#
| Write | Goes to |
|---|---|
[World](api:World) | the API entry for World, wherever it lives |
[the package](pkg:physics) | that package's API page |
[Levels](concepts/levels.md#the-manifest) | another guide, optionally to a heading (relative to the current file) |
A link to an API name or guide that does not exist is reported when the site is built, so a rename in the code shows up as a warning here.
The API reference#
tools/docs/api.mjs reads every package's src/index.ts with the TypeScript compiler. For each export it takes the signature, the doc comment and the public members of classes, interfaces and enums. Things re-exported from another package are documented where they are defined. To document something, write a /** ... */ comment on it. The first paragraph is the summary shown in lists and search.
docs/packages.json says which group a package belongs to and gives its one-line summary. The build warns about a package without an entry.
Search#
The build writes assets/search.json (guides, their headings, packages, exports and members) and assets/search.js filters it in the browser. Press / to focus the search box.