Writing the documentation
This page is for anyone who adds or changes a page under docs/. It gives the folder each page belongs
in, the bilingual rule, a page template, the house style, and the two commands that keep the reference
pages and links honest.
Where a page goes
| Folder | Reader | Content |
|---|---|---|
docs/start/ |
everyone | install, connect an assistant, first steps |
docs/learn/ |
students and self-learners | how to learn and review with Studium |
docs/teach/ |
teachers | authoring, review and approval, following a class |
docs/tutorials/ |
everyone | one worked task from start to result |
docs/concepts/ |
everyone | how Studium works and why; the glossary |
docs/reference/ |
developers and power users | tools, bundle format, configuration, CLI, HTTP API |
docs/develop/ |
contributors | architecture, testing, release, this page |
docs/design-records/ |
maintainers | specifications, ADRs, audits; archives, see the index |
docs/internal/ |
maintainers and agents | the agent log and the handoff history |
The portal docs/index.md links every reader's path; a new page gets a link from it or from a page it already links.
Two languages, one structure
Every page under docs/ exists twice: page.md in English and page.fr.md in French. Both have the same
headings in the same order, the same tables and the same commands. The French page is written in natural
French and addresses the reader as « vous »; it is not a word-for-word translation.
The first line of each page is the language switch, exactly:
English · [Français](page.fr.md)
on the English page, and on the French page:
[English](page.md) · Français
Three exceptions:
docs/design-records/keeps each record in its original language; only its index has two versions.docs/internal/is single-language working material.- In a generated reference page, the generated tables stay in English on both versions; the prose around them is translated.
The root README follows the same rule (README.md and README.fr.md).
Page template
English · [Français](my-page.fr.md)
# Title that names the task or the subject
One or two sentences: what the reader can do with this page and what they get.
## Before you start
What must be installed or known, with links.
## Do the task
1. A step.
2. A step, with the command:
```bash
pnpm --filter @studium/lesson-mcp start
```
## What you get
The result, and how to check it.
## Limits
What this does not do, said once.
House style
- Lead with what the reader can do and the result. One H1, then H2 and H3 only.
- Aim for 60 to 200 lines. Split a longer page by task.
- Use a table for parallel facts and a fenced
bashblock for commands. Commands are copy-pasteable and use repository-relative paths, never a path on your own machine. - Explain a term at first use or link the glossary.
- No emoji, no hype, no dates that will go stale. "Since
" is fine when it helps. - State a limit plainly, once, in the place the reader needs it.
- Document only what the code does. Before you write a command, a flag, a tool or a default, find it in the code. When a feature goes away, its documentation goes with it.
Links and images
Link pages and code with relative paths, for example [testing](testing.md) or
[server.ts](../../apps/lesson-mcp/src/server.ts). Images live in docs/assets/. When an image has light
and dark versions, use both, with alt text that says what the image shows:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="../assets/diagrams/architecture-dark.svg">
<img src="../assets/diagrams/architecture-light.svg" alt="What the diagram shows, in one sentence.">
</picture>
Generated reference pages
Parts of docs/reference/ are written by scripts from the code. The generated part of a page sits between
two markers; everything outside them is written by hand and stays editable in both languages:
<!-- BEGIN GENERATED: mcp-tools (tools/docs/gen-mcp-tools.mjs; do not edit by hand) -->
<!-- END GENERATED: mcp-tools -->
| Script | Pages | Source |
|---|---|---|
tools/docs/gen-mcp-tools.mjs |
docs/reference/mcp-tools.md and .fr.md |
the running MCP server: tools, input fields, prompts, instructions |
tools/docs/gen-lesson-bundle.mjs |
docs/reference/lesson-bundle.md and .fr.md |
the Zod schemas of packages/lesson-bundle-schema |
After changing a tool or the bundle schema, regenerate and commit the result with the code change:
node tools/docs/gen-mcp-tools.mjs
node tools/docs/gen-lesson-bundle.mjs
node tools/docs/gen-mcp-tools.mjs --check # exit 1 when a page is out of date
The generators run the code through the workspace tsx with STUDIUM_EPHEMERAL=1, so pnpm install must
have run and no learner state is written.
The docs check
tools/docs/check.mjs is the documentation gate. Run it before you open a
pull request:
node tools/docs/check.mjs # everything; exit 1 on any problem
node tools/docs/check.mjs --skip-generated # links and pairs only, without running TypeScript
node --test tools/docs/check.test.mjs # tests of the check itself
It checks that:
- every relative link and
#anchorin every Markdown file of the repository resolves; - every page under
docs/, outsidedesign-records/andinternal/, has its English or French twin; - every tool the MCP server registers has a section in
docs/reference/mcp-tools.md; - the generated regions match the code;
- the first line of every page that has a twin, and of the root
README, is the language-switch line (English · [Français](page.fr.md)or[English](page.md) · Français); - every page of
docs/start,learn,teach,tutorials,concepts,referenceanddevelopis linked fromdocs/index.md(English pages) ordocs/index.fr.md(French pages); - an image whose name ends in
-lighthas its-darktwin on disk, and the reverse, and every image has an alt text. A single-theme image goes inSINGLE_THEME_IMAGESincheck.mjs, with the reason; - as a warning only, which does not change the exit code: a page under
docs/longer than 200 lines is listed with its line count (pages with a generated region are skipped).
It does not check that both versions say the same thing, or that a command works. Those are for the reviewer.
Build the site
tools/docs/build-site.mjs renders the same pages as a small static
site, in the project's identity: a sidebar, a table of contents, a search box, a button to copy each
code block, both languages, light and dark themes, a print layout.
pnpm docs:site # writes site/ at the repository root
node tools/docs/build-site.mjs --out /tmp/studium-docs --revision v0.5.0
node --test tools/docs/build-site.test.mjs # tests of the builder
It reads README.md, README.fr.md and every page of docs/ except design-records/ and internal/,
puts the English pages at the root and the French pages under fr/, and builds the navigation from
the portal (the role table, then the « All pages » groups). Links to other files of the repository, such
as source code, go to GitHub. It needs no network, at build time or to read the result, and it exits 1
when a link or an anchor of the built site leads nowhere. --revision names in the footer the version
or commit the site was built from.
The search needs no server: the builder writes one index per language (search-index.js and
fr/search-index.js: titles, headings and the text of each page without its code blocks), loaded when
the search box first gets the focus. It ignores case and accents, and / puts the focus in the box.
The site opens from the file system and from any sub-path. The workflow
docs-site.yml builds it on each push to main that touches
the documentation and publishes it to GitHub Pages, once Pages is enabled in the repository settings
with « GitHub Actions » as its source.
site/ is not committed. The Markdown is the source: write and check every page for GitHub first, where
it must read well too.