sklein-markdown

name	sklein-markdown
description	Préférences Markdown de Stéphane Klein. Conventions de formatage pour les listes, les tableaux, la structure et la mise en forme.

sklein-markdown

Conventions de formatage Markdown pour toute rédaction.

Général

• Utiliser - pour les listes à puces (pas *).
• Utiliser **gras** pour l'emphase (pas __gras__ ni *italique* pour l'emphase principale).

Listes

Espacement des listes

Format préféré : une ligne vide sépare le paragraphe introductif de la liste, mais pas de ligne vide au sein de la liste.

Paragraphe:

- item 1
- item 2
  - item 2.1
  - item 2.2
- item 3

Format à éviter : pas de ligne vide entre le paragraphe et la liste, ni de ligne vide au milieu de la liste.

Paragraphe:
- item 1
- item 2
  - item 2.1
  - item 2.2

- item 3

Listes imbriquées

• Utiliser 2 espaces pour l'indentation des sous-listes.
• Ne pas insérer de ligne vide entre un item parent et ses enfants.

Tableaux

• Utiliser des tableaux Markdown avec les colonnes alignées via les deux-points :.
• Aligner à gauche :---, centrer :---:, aligner à droite ---:.

Exemple :

| Colonne 1 | Colonne 2 | Colonne 3 |
|:----------|:---------:|----------:|
| Gauche    | Centré    | Droite    |

Terminal sessions

Convention d'affichage

• Les lignes commençant par $ indiquent une commande utilisateur.
• Les lignes commençant par # indiquent une commande root.
• Les lignes sans préfixe sont la sortie du terminal.
• Les commentaires en fin de ligne utilisent # ….

$ echo "Hello, world!"
Hello, world!

$ sudo su
# systemctl restart nginx
$ exit

$ uptime # Affiche l'uptime

Toujours utiliser $ (y compris sans sortie)

Contrairement à la règle MD014 (omettre $ quand il n'y a pas de sortie), toujours préfixer les commandes par $, même si le bloc ne contient que des commandes sans sortie.

Justification : dans une documentation qui mélange fichiers de configuration et commandes, l'absence de $ crée une ambiguïté entre ce qui est à exécuter et ce qui est de la configuration.

Ces blocs sont des "screenshots" explicatifs

Ils n'ont pas vocation à être copiés/collés en masse. Si un groupe de commandes est fréquemment copié, le remplacer par un script helper (voir sklein-helper-scripts).

Liens vers dossiers

Quand un README liste les dossiers d'un projet, chaque entrée doit être un lien cliquable vers le dossier concerné :

- [`01-fedora-minimal-mutable/`](./01-fedora-minimal-mutable/) — Description.
- [`02-fedora-minimal-bootc/`](./02-fedora-minimal-bootc/) — Description.

Format : [`nom-dossier/`](./nom-dossier/) — backticks + slash + lien relatif.

Scope

Ces conventions s'appliquent à tout Markdown, sauf si le projet concerné définit déjà ses propres conventions de formatage.