Improve these docs

How to fix or add a page on this docs site, from the facts rule and the claim ledgers to the prose lints and the figure kit.

Last page covered the rules for the Markless repo. This site lives in a different repo with its own short list.

These docs are a community site built with Blume. One rule beats every other rule: each fact on a page comes from the Markless code.

Run the site

You need Node 22.12 or newer and pnpm.

git clone https://github.com/thejackshelton/markless-temp-docs.git
cd markless-temp-docs
pnpm install
pnpm dev

Command	What it does
`pnpm dev`	Starts the Blume dev server
`pnpm lint:prose`	Checks sentence length, banned words, passive voice and `-ing` clauses
`pnpm lint:audience`	Finds hardcoded sizes anywhere, and technical words on beginner pages
`pnpm typecheck`	Typechecks `lib/` and `islands/` with `tsconfig.islands.json`
`pnpm gen:errors`	Reads the Markless source for `MARKLESS_*` error codes and writes the pages in `docs/errors/`
`pnpm build`	Builds the static site

pnpm gen:errors looks for the Markless repo at ../markless. Pass --markless=<path> or set MARKLESS_SRC if your copy lives somewhere else.

Where things live

docs/<section>/*.mdx holds the pages. Each folder has a meta.ts with its title, icon and page order.
STYLE.md holds the voice and sentence rules.
goals/markless-temp-docs/claims/<section>/<page>.md holds the claim ledger for each page.
islands/*.tsx holds the interactive figures. One file is one figure.
lib/fig/ is the figure kit: Figure, CodePane, Flash, Ledger, Tally, Timeline, Segmented and BrowserFrame.
goals/markless-temp-docs/notes/FIGURES.md is the figure spec. Read it before you build a figure.

Facts come from the code

Check every API name, import path and command against the Markless source before you write it. Good sources are package code, tests, fixtures, demos and CLI templates.

Do not copy prose from markless/website.
Treat specs as pointers, not proof.
If you cannot check a fact, leave it out.
Do not write sizes or timings. They change every release.

Each page has a claim ledger. It lists every fact on the page, the Markless file and line that proves it, and how you checked it. A reviewer checks the ledger against the code.

| Claim | Source | Checked by |
| --- | --- | --- |
| pnpm is pinned to 10.33.2 | `package.json:64` (`packageManager`) | read |

Write a page

Read STYLE.md first. The short version:

Keep sentences to 20 words or fewer.
Use active voice. Use only can, will and must as modals.
Let the figure explain. Keep paragraphs to one to three sentences.
Open with one sentence that picks up the last page. End with a Next: link.
Give every callout a specific title, such as “Why did my handler not run?”.
On beginner pages, use plain words. Save technical terms for Under the hood.

Add a figure

A figure is a React component in islands/. Name the file in PascalCase, such as islands/StateWireFigure.tsx. Then put <StateWireFigure /> in any page, with no import.

Build it from the kit in lib/fig/. Then every figure uses the same colors for your code, the page, and what Markless did.

One figure teaches one idea.
Put the controls in real <button> elements, so keyboard users can operate them.
The readout says rest at the start and changes on every click.
Keep the first render deterministic. Do not use Math.random or window during render.
Accent marks the one thing that changes right now.

Open a pull request

Make a branch

Branch off main in the docs repo.

Check your work

Run pnpm lint:prose, pnpm lint:audience and pnpm typecheck. Then run pnpm build.

Open the PR

Add or update the claim ledger for each page you changed. A reviewer checks each line against the Markless source.

Next: Which package exports which API? Packages →