Contributing to the documentation

This site is built with Astro 🡕 and Starlight 🡕. Pages live under src/content/docs/<lang>/ (fr, en).

Where to write

doc/<section>.mdx : entry page of a section, introduction + links.
doc/<section>/<feuille>.mdx : detail pages.
Short cross-cutting topics → doc/how-to/{user,admin,dev}/.

Write in French (fr/) ; English is produced afterwards by just translate. Slugs and file names stay in English.

Essential Rules

Max 7 headings per level, depth 3.
<Steps> for step sequences, <Aside> (with title) for callouts.
Card/CardGrid are reserved for the user guide.
See the help & how-to dev and role skills.

Tools

just dev      # development server
just tags     # refresh translation tags
just build    # build the static site
just test     # tests + internal link validation

Languages and translation

Write only in French (fr/) ; English (en/) is produced by just translate. Never edit en/ manually.

Action	To do
Create a page	In `fr/` only ; do not run `just translate`.
Move a page	Move both languages together (files, verbatim), then `just tags`.
Translate	At the end of the work: `just tags` then `just translate`.

Translation markers are managed by the scripts, never manually:

Marker	Role
`{/* t:main */}`	Source-of-truth file for a page.
`{/* t:translated-from <lang> */}`	Translated file (do not modify).
`{/* t:h <hash> */}`	Frontmatter hash.
`{/* t:p <hash> */}`	Paragraph hash (before each block).

Links and anchors

Internal links in /fr/...; validated at build by starlight-links-validator.
An anchor = github-slugger slug of the target heading text (## Mon Titre → #mon-titre).
Check: just build (fails on a dead link) or just check-links.

Making beautiful pages

The validated recipe (short items, colored callouts, <Steps>, tables, D2 diagrams, generic examples) is detailed in AGENTS.md → Making “beautiful” pages. To be followed according to the persona :

Persona	Tone
User	Inspire, no jargon; `Card`/`LinkCard` allowed.
Administrator	Precise, operational; tables and callouts.
Developer / AI	Hierarchy (where → detail), step by step, concise.