Writing the documentation¶

This site is built by zensical, the successor of mkdocs-material, from the Markdown files under docs/. The published copy at https://heig-tin-info.github.io/heig-quiz/ is rebuilt by GitHub Actions; a local copy is one command away.

Building it locally¶

zensical is a Python tool. Install it once, either as an isolated tool or into any Python environment:

uv tool install zensical      # or: pip install zensical

Then, from the root of the repository:

pnpm docs:serve               # zensical serve: live reload on http://127.0.0.1:8000
pnpm docs:build               # zensical build: the static site in site/ (gitignored)

uvx zensical serve works too, without installing anything.

Where things are¶

The nav array of zensical.toml controls the site navigation: one tab per audience. Guide is for teachers and students; Operations for whoever hosts the platform (deployment, a new server, the GitHub App, Teams, the kiosk stations); Developers, last, for contributors and agents, with the specification and the decision records as collapsed groups under "Reference" (zensical takes a README.md that is a direct child of a group as that group's index page, which is why each is a group of its own). The classroom merge record (merge/) left the nav with the cutover of 2026-10-11 and follows the archive rule below; the developer index keeps its entry link. A page that is built but listed nowhere is reached only through the links of the current pages: the ADR records, through the decision index, and every archived page (below). Links between pages are relative Markdown links to the .md file (../spec/05-architecture.md, deployment.md#rollback); zensical rewrites them at build time and warns about a target that does not exist, which is the check to read after pnpm docs:build.

Current context and history¶

Current specs and consolidated ADRs state the rules an agent should apply. Move long delivery chronicles and superseded alternatives into history/ only with a link back to the current source and a clear historical notice. Archived pages use search: { exclude: true } in YAML front matter so the site search does not present obsolete instructions alongside current ones, and they are never listed in the nav: the repository is public, so an archive is public whatever the site does, and the one lever is discoverability. They stay in the repository because the sources cite them (the "PLAN-MVP §x.y" comments, the former ADR addenda) and an agent in a worktree or a shallow clone cannot resolve such a citation from git history. Preserve existing URLs and section anchors as pointers when consolidating. 2026-10-09: an anchor list into history/ may be reduced to a correspondence table of the cited sections plus bare compatibility anchors.

Do not archive unresolved product questions or remove an accepted requirement because its code is not implemented. Record a verified delivery boundary and link its task. Exact library versions and declarations belong in manifests, contracts and schemas; documentation explains their purpose and constraints.

Publication¶

.github/workflows/docs.yml runs on every push to main that touches docs/**, zensical.toml or the workflow itself, and on the matching pull requests. It installs Python 3.12 and zensical, runs zensical build, and on a push deploys the site/ directory to GitHub Pages. A pull request only builds, which is enough to catch a broken link or a bad admonition before merging. The workflow can also be started by hand from the Actions tab (workflow_dispatch).

Language and style¶

Everything on this site is in English, like everything else in the repository that is not a string a user reads (invariant 1). The specification and the decision records were written in French and have been translated; the file names under docs/spec/ and docs/adr/ keep their original French slugs, so existing links and the nav keep working.

The style of these pages: precise prose in short paragraphs, a table where things are parallel, a fenced code block for every command, and no paraphrase of a source file when a link to it will do. Section headings are sentence case.

The Markdown extensions enabled in zensical.toml include admonitions and collapsible blocks:

!!! note "Optional title"

    Body, indented by four spaces.

!!! warning

    Same syntax, different colour.

??? info "Click to expand"

    A collapsible block, closed by default. `???+` opens it by default.

Also available: footnotes, definition lists, task lists, attr_list and md_in_html (which is what the card grid on the home page uses), fenced code blocks with syntax highlighting and a copy button, and Mermaid diagrams in a ```mermaid fence. Content tabs are not enabled; use headings or a table instead.

Images in light and dark¶

Every screenshot exists twice, <name>-light.png and <name>-dark.png, and a page embeds both so that the theme shows the one matching its palette. The markup, and the pipeline that produces both files for every screen, are described on their own page: screenshots.