Contribuer à la documentation

Ce site est construit avec Astro 🡕 et Starlight 🡕. Les pages vivent sous src/content/docs/<lang>/ (fr, en).

Où écrire

doc/<section>.mdx : page d’entrée d’une section, introduction + liens.
doc/<section>/<feuille>.mdx : feuilles de détail.
Sujets transverses courts → doc/how-to/{user,admin,dev}/.

On rédige en français (fr/) ; l’anglais est produit ensuite par just translate. Les slugs et noms de fichiers restent en anglais.

Règles essentielles

Max 7 titres par niveau, profondeur 3.
<Steps> pour les suites d’étapes, <Aside> (avec titre) pour les remarques.
Les Card/CardGrid sont réservées au guide utilisateur.
Voir l’aide & how-to dev et les skills de rôle.

Outils

just dev      # serveur de développement
just tags     # rafraîchit les tags de traduction
just build    # construit le site statique
just test     # tests + validation des liens internes

Langues et traduction

On écrit uniquement en français (fr/) ; l’anglais (en/) est produit par just translate. Ne jamais éditer en/ à la main.

Action	À faire
Créer une page	En `fr/` seulement ; ne pas lancer `just translate`.
Déplacer une page	Bouger les deux langues ensemble (fichiers, verbatim), puis `just tags`.
Traduire	En fin de chantier : `just tags` puis `just translate`.

Les marqueurs de traduction sont gérés par les scripts, jamais à la main :

Marqueur	Rôle
`{/* t:main */}`	Fichier source de vérité d’une page.
`{/* t:translated-from <lang> */}`	Fichier traduit (ne pas modifier).
`{/* t:h <hash> */}`	Hash du frontmatter.
`{/* t:p <hash> */}`	Hash d’un paragraphe (avant chaque bloc).

Liens et ancres

Liens internes en /fr/... ; validés au build par starlight-links-validator.
Une ancre = slug github-slugger du texte du titre cible (## Mon Titre → #mon-titre).
Vérifier : just build (échoue sur un lien mort) ou just check-links.

Faire de belles pages

La recette validée (items courts, callouts colorés, <Steps>, tableaux, schémas D2, exemples génériques) est détaillée dans AGENTS.md → Faire de « belles » pages. À respecter selon le persona :

Persona	Ton
Utilisateur	Donner envie, sans jargon ; `Card`/`LinkCard` autorisées.
Administrateur	Précis, opérationnel ; tableaux et callouts.
Développeur / IA	Hiérarchie (où → détail), étape par étape, concis.