Markdown : la syntaxe pour écrire sa documentation

Markdown est un langage de balisage léger : tu écris du texte brut avec quelques symboles (#, *, -, `), et un logiciel les transforme en titres, listes, liens, tableaux et blocs de code. Créé en 2004 par John Gruber, il est devenu le format des fichiers README.md, des wikis, des générateurs de sites de documentation et de la plupart des outils de développement. Ce chapitre donne toute la syntaxe utile, les extensions de GitHub et les pièges qui cassent un rendu.

Pourquoi documenter en Markdown

• Le fichier reste lisible sans rendu. Un # devant un titre, des tirets devant une liste : même ouvert dans le Bloc-notes ou avec cat, le texte se comprend.
• Il se versionne avec Git. C'est du texte : git diff montre exactement les lignes modifiées, une pull request permet de relire une documentation comme du code. Un fichier .docx est une archive binaire, dont Git ne sait pas montrer les différences.
• Il s'affiche partout. GitHub et GitLab l'affichent dans le navigateur, VS Code a un aperçu intégré, les wikis BookStack et Wiki.js ont un éditeur Markdown, et les générateurs de sites de documentation (chapitre 6) le transforment en site web.
• Il se convertit. Un outil comme Pandoc produit un fichier Word, HTML ou PDF à partir du même fichier.

Sa limite : il n'existe pas un Markdown. La spécification de référence s'appelle CommonMark (version 0.31.2, publiée en janvier 2024) ; GitHub l'étend avec le GitHub Flavored Markdown (GFM), qui ajoute les tableaux, les cases à cocher, le texte barré et les liens automatiques. Chaque outil ajoute ensuite ses propres extensions. Ce chapitre signale ce qui n'est pas du CommonMark de base.

Titres et paragraphes

Un titre commence par un à six #, suivis d'une espace. Un paragraphe est un bloc de lignes séparé des autres par une ligne vide.

# Wiki interne de Sorbier Logistique

Le wiki rassemble les procédures et les guides du service informatique.
Cette phrase, écrite à la ligne, appartient au même paragraphe.

## Installation

### Prérequis

• Un seul titre de niveau 1 par document : le nom du projet ou du document. Les sections sont en ##, les sous-sections en ###.
• Pas de saut de niveau : un ### vient sous un ##, jamais directement sous un #.
• Un retour à la ligne simple ne crée pas de nouvelle ligne dans le rendu : les deux lignes du paragraphe ci-dessus s'affichent bout à bout. Pour forcer un retour à la ligne sans changer de paragraphe, termine la ligne par une barre oblique inverse \ (ou par deux espaces, invisibles et donc fragiles). Le plus souvent, une ligne vide pour un nouveau paragraphe est la meilleure solution.

Mettre en forme le texte

Le service **doit** être redémarré. Le terme *idempotent* est défini plus bas.
Tape `systemctl status nginx` pour vérifier. ~~Ancienne adresse~~ (GFM)
Pour afficher un astérisque littéral, échappe-le : 5 \* 3.

Les listes

Prérequis :

- un compte d'administration Proxmox ;
- le modèle 9000 ;
- une adresse réservée dans le plan d'adressage.

1. Crée le clone.
2. Branche la carte dans le VLAN 21.
   - Le modèle est dans le VLAN 20 : ne saute pas cette étape.
3. Démarre la VM.

• Une liste à puces commence par - (ou *, ou + : choisis un symbole et garde-le).
• Une liste numérotée commence par 1. ; le rendu renumérote tout seul, mais écris les vrais numéros : le fichier brut doit rester lisible.
• Une sous-liste est indentée pour s'aligner sous le texte de l'élément parent : trois espaces sous 1. , deux sous - .
• Laisse une ligne vide avant une liste : collée à un paragraphe, elle s'affiche bien sur GitHub, mais Zensical, MkDocs et certains wikis la collent au paragraphe, comme du texte ordinaire.

Liens et images

Voir la [procédure de déploiement](docs/exploitation/deploiement.md).
Voir la section [Installation](#installation) de ce document.
Documentation officielle : [Proxmox VE](https://pve.proxmox.com/pve-docs/).

![Onglet Hardware de la VM 190 : la carte net0 est sur vmbr0 avec le tag 21](img/vm190-hardware.png)

• [texte](adresse) crée un lien. Le texte doit dire où mène le lien : « procédure de déploiement », jamais « ici ».
• Un lien relatif (docs/exploitation/deploiement.md) pointe vers un fichier du même dépôt : il continue de fonctionner quand le dépôt est cloné, déplacé ou publié. Sur GitHub, il suit la branche que tu consultes.
• #installation pointe vers un titre du même document : les outils fabriquent l'ancre à partir du texte du titre, en minuscules, les espaces remplacées par des tirets.
• Une image s'écrit comme un lien précédé de ! ; le texte entre crochets est le texte alternatif, qui décrit l'image pour ceux qui ne la voient pas (chapitre 2). Range les images dans un dossier img/ ou docs/img/ à côté des fichiers Markdown.

Les blocs de code

Tout ce qui se tape ou se copie va dans un bloc de code, entouré de trois accents graves, avec le nom du langage pour la coloration :

```bash
qm clone 9000 190 --name srv-wiki --full --storage truenas-nfs
```

```powershell
Resolve-DnsName srv-wiki.ad.sorbier.example
```

```yaml
openapi: 3.1.2
```

Les noms de langage les plus utiles : bash, powershell, sql, python, javascript, csharp, php, yaml, json, ini, nginx, et text pour un contenu sans coloration (une sortie de commande, un fichier de journal). Pour montrer un bloc de code à l'intérieur d'un exemple Markdown, comme ci-dessus, entoure le tout de quatre accents graves.

Les tableaux

Les tableaux viennent du GitHub Flavored Markdown ; la plupart des outils les acceptent.

| VLAN | Nom    | Réseau            | Passerelle     |
|-----:|--------|-------------------|----------------|
| 20   | SERVEURS | 192.168.10.176/28 | 192.168.10.190 |
| 21   | APPLIS | 192.168.21.0/24   | 192.168.21.254 |

• La deuxième ligne, faite de tirets, transforme la première en ligne d'en-tête ; elle doit avoir le même nombre de colonnes.
• Les deux-points règlent l'alignement : :--- à gauche, :---: au centre, ---: à droite (utile pour les nombres).
• Les colonnes n'ont pas besoin d'être alignées dans le fichier brut : c'est plus joli, pas obligatoire.
• Une barre verticale dans une cellule s'écrit \|.
• Pas de cellules fusionnées ni de retour à la ligne dans une cellule : si ton tableau en a besoin, c'est qu'il faut le découper ou en faire une liste.

Citations, alertes et autres extensions

> Une citation : un message d'erreur, la demande d'un utilisateur.

> [!WARNING]
> L'étape suivante redémarre le serveur.

- [x] Plan d'adressage mis à jour
- [ ] VM ajoutée à la supervision

La sauvegarde suit la règle 3-2-1[^1].

[^1]: Trois copies, deux supports, une copie hors site.

---

• > crée une citation.
• > [!NOTE] en première ligne d'une citation crée une alerte sur GitHub, qui en connaît cinq : NOTE (une information utile), TIP (un conseil), IMPORTANT (une information nécessaire pour réussir), WARNING (un risque à connaître tout de suite) et CAUTION (les conséquences négatives d'une action). GitHub recommande d'en mettre peu, une ou deux par page, et jamais l'une dans l'autre. D'autres outils ont leur propre syntaxe : !!! note pour Zensical et MkDocs, :::note pour Docusaurus.
• - [ ] et - [x] font des cases à cocher (GFM), pratiques pour une liste de contrôle.
• [^1] crée une note de bas de page (GFM).
• --- seul sur sa ligne, entre deux lignes vides, trace une ligne horizontale.

Des diagrammes en texte avec Mermaid

GitHub, GitLab et la plupart des outils de documentation affichent un bloc de code marqué mermaid comme un diagramme. Le schéma vit dans le fichier, se versionne et se modifie comme du texte :

```mermaid
flowchart LR
    P["Postes<br/>VLAN 10"] --> F["pfSense pf1"]
    F --> W["srv-wiki<br/>VLAN 21"]
    F --> AD["srv-ad, srv-ad2<br/>VLAN 20"]
    W -. "authentification LDAPS" .-> AD
```

Mermaid est idéal pour un petit schéma de flux ou un diagramme de séquence dans un README. Pour un schéma réseau complet, avec des icônes et une mise en page soignée, draw.io reste plus adapté (chapitre 9). Le cours UML compare Mermaid, PlantUML et draw.io.

Les pièges du Markdown

Les outils

• VS Code : ouvre l'aperçu avec Ctrl + Maj + V, ou à côté du fichier avec Ctrl + K puis V. L'extension markdownlint signale les erreurs de structure au fil de la frappe (saut de niveau de titre, ligne vide manquante autour d'un titre ou d'une liste).
• Pandoc convertit un fichier Markdown dans de nombreux formats : pandoc guide.md -o guide.docx produit un document Word, utile quand un client exige ce format. La conversion en PDF passe par un moteur PDF à installer en plus.
• Les wikis et les générateurs de sites ont leur éditeur ou leur aperçu ; ils ajoutent souvent leurs propres extensions, à vérifier dans leur documentation avant de s'en servir.

Exercices

## Variables d'environnement

Le fichier `.env.example` sert de modèle : copie-le, puis remplis tes valeurs.

| Variable | Rôle | Exemple |
|---|---|---|
| `PORT` | Port d'écoute de l'API | `3000` |
| `DB_HOST` | Adresse du serveur MySQL | `192.168.21.23` |

```bash
cp .env.example .env
```

# Wiki de Sorbier
### Sauvegarde
Les étapes :
1. Arrêter le service
2. Lancer le script
'''bash
sudo /opt/wiki/sauvegarde.sh
'''
| Fichier | Rôle |
| sauvegarde.sh | Sauvegarde la base et les pièces jointes |

```mermaid
flowchart LR
    O["Ouvert"] --> C["En cours"]
    C --> R["Résolu"]
    R -- "l'utilisateur conteste" --> C
```