Contribuer à cette documentation¶

Comment ajouter ou modifier une page de ce site. Aucune connaissance technique n'est nécessaire pour suivre ces étapes — juste un éditeur de texte et, pour prévisualiser, la commande mkdocs serve (voir README.md).

Modifier une page existante¶

Chaque page du site est un fichier Markdown (.md) dans le dossier docs/. Éditer le fichier, sauvegarder : si mkdocs serve tourne, la page se recharge automatiquement dans le navigateur.

Ajouter une nouvelle page¶

1. Créer le fichier .md dans docs/ (ou un sous-dossier, ex. docs/projets/ pour une page liée à un projet).

2. L'ajouter à la section nav: de mkdocs.yml, sinon la page existe mais n'apparaît dans aucun menu :

   nav:
     - Vue d'ensemble: index.md
     - Ma nouvelle page: ma-page.md
   

   Le chemin est relatif à docs/.

3. Relancer mkdocs serve si la commande n'était pas déjà en cours (l'ajout d'une page à nav: nécessite un redémarrage ; les modifications de contenu, elles, se rechargent automatiquement).

Importer le README d'un des 5 projets¶

Ce site est un miroir, pas une deuxième source de vérité (voir le CLAUDE.md du dossier parent lcl/) : le contenu doit rester fidèle au README.md du dépôt d'origine, pas diverger avec le temps.

• Copier/adapter le contenu du README.md du dépôt, sans réinventer l'information.
• Si le README source change plus tard, revenir mettre à jour la page ici — ce site n'est pas branché automatiquement sur les autres dépôts.
• Ne pas copier de secret (mot de passe, clé d'API) même si, par erreur, il se trouvait dans le README source.

Syntaxe disponible¶

En plus du Markdown de base, ces extensions sont activées (voir markdown_extensions: dans mkdocs.yml) :

Encadrés (admonitions)¶

!!! warning "Titre optionnel"
    Le contenu de l'encadré, indenté de 4 espaces.

Rendu :

Autres types utiles : note, info, tip, danger. Voir des exemples réels dans docs/infrastructure.md ou docs/projets/lcl-rapports.md.

Schémas (Mermaid)¶

```mermaid
flowchart LR
    A --> B
```

Rendu directement comme un diagramme (voir docs/index.md pour un exemple avec plusieurs projets reliés entre eux).

Onglets¶

=== "Onglet 1"
    Contenu du premier onglet.

=== "Onglet 2"
    Contenu du deuxième onglet.

Bouton (lien stylisé)¶

[Texte du bouton](cible.md){ .md-button }

Ajouter .md-button--primary pour un bouton bleu plein (voir le bouton de téléchargement du PDF en haut de docs/index.md).

Le PDF combiné¶

Le bouton Télécharger toute la documentation en PDF de la page d'accueil pointe vers assets/lcl-documentation.pdf, un fichier qui n'existe pas après un simple mkdocs build : il n'est généré que par la config séparée mkdocs.pdf.yml, et copié à cet endroit par le Dockerfile (voir la section Utilisation du README.md). Ajouter une page à nav: l'ajoute automatiquement au PDF — aucune configuration séparée n'est nécessaire pour ça.

Avant de considérer une modification terminée¶

• Lancer mkdocs build (ou mkdocs serve) et vérifier visuellement la page modifiée — les erreurs de syntaxe Markdown/YAML ne sont pas toujours bruyantes.
• Si la modification touche nav: ou une nouvelle page, vérifier qu'elle apparaît bien dans le menu et qu'aucun lien interne n'est cassé (mkdocs build averti dans son log si un lien pointe vers un fichier introuvable).