Aide-Mémoire Markdown

À propos de l'Aide-Mémoire Markdown

Quelle est la différence entre CommonMark et GitHub Flavored Markdown ?

CommonMark est la spécification non ambiguë du Markdown publiée en 2014 qui résout les dizaines de cas limites laissés vagues dans la description originale de John Gruber de 2004. GitHub Flavored Markdown (GFM) est un sur-ensemble strict de CommonMark - tout ce que CommonMark supporte est supporté en GFM à l'identique, et la spécification GFM ajoute tableaux, listes de tâches, barré, liens automatiques et quelques règles supplémentaires. Les fonctions plus récentes spécifiques à GitHub - encadrés (> [!NOTE]), sections pliables, code clôturé coloré et codes d'emoji - ne font pas strictement partie de GFM mais GitHub les rend quand même. Cet aide-mémoire les étiquette 'Extensions GFM' pour commodité, mais tous les moteurs Markdown ne les rendront pas ; pour des documents portables, restez sur CommonMark pur.

Pourquoi ma liste ne s'affiche-t-elle pas correctement ?

Le problème de rendu Markdown le plus courant est l'absence de la ligne vide qui sépare la liste du paragraphe environnant. CommonMark exige une ligne vide avant toute liste, sinon le premier élément se colle au texte précédent en un seul paragraphe. Le deuxième problème courant est l'indentation d'imbrication : chaque niveau doit être indenté exactement de la largeur du marqueur plus un espace (typiquement deux espaces pour les listes non ordonnées, trois ou quatre pour les ordonnées). Si un élément imbriqué refuse de s'indenter, vérifiez que la ligne parente ne se termine pas par un espace en trop et que vous avez utilisé des espaces, pas des tabulations. Enfin, certains anciens parseurs n'acceptent pas de chiffres autres que 1 comme premier élément de liste ordonnée ; CommonMark accepte n'importe quel chiffre et les rend en séquence.

Comment échapper les caractères spéciaux de Markdown ?

Placez un antislash avant tout caractère que Markdown interpréterait : \*pas italique\*, \#pas-de-titre, \[pas-de-lien\]. Les caractères échappables sont : \ ` * _ { } [ ] ( ) # + - . ! | > et ~. En dehors, un antislash reste tel quel. Cas plus subtil : pour des backticks à l'intérieur du code en ligne, entourez votre code d'une plus longue suite de backticks, donc ``code avec ` dedans`` devient <code>code avec ` dedans</code>. Pour les antislashes eux-mêmes, doublez-les : \\. La plupart des éditeurs avec aperçu Markdown vous montrent immédiatement si l'échappement a fonctionné, donc utilisez un aperçu en direct en cas de doute.

Les encadrés GitHub sont-ils portables vers d'autres outils ?

La syntaxe d'encadrés > [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT] / [!CAUTION] a été introduite par GitHub fin 2023 et adoptée peu après par GitLab. Les rendus qui ne l'ont pas implémentée (la plupart des générateurs statiques, Notion et anciens éditeurs Markdown) traitent le bloc comme une simple citation, ce qui est élégant : l'avertissement reste lisible, sans la bannière colorée. Si vous publiez vers une plate-forme comme MkDocs, Hugo ou Jekyll, préférez la syntaxe d'admonition native (par exemple !!! note ... dans MkDocs Material). Pour une portabilité maximale, écrivez les encadrés en citations préfixées en gras : > **Note :** ... qui se rend correctement partout.

Comment écrire des équations mathématiques en Markdown ?

La math en ligne se met entre dollars simples : $E = mc^2$. La math en bloc entre doubles dollars sur leurs propres lignes, comme $$\int_0^1 x^2 dx$$. Le rendu effectif dépend du moteur : GitHub, GitLab, Obsidian, Notion et Quarto supportent TeX/LaTeX nativement via KaTeX ou MathJax ; CommonMark classique non. Si vous publiez via un générateur statique, installez un plugin math (rehype-katex pour unified, mkdocs-material avec arithmatex pour MkDocs, hugo-katex pour Hugo). Échappez les dollars isolés représentant une devise avec un antislash : \$5, sinon le moteur peut tenter d'entrer en mode math et produire une sortie étrange.

Comment faire un tableau en Markdown et aligner les colonnes ?

Les tableaux utilisent des barres verticales pour séparer les colonnes et une ligne de séparation faite de tirets pour séparer l'en-tête du corps : | Nom | Score | sur la première ligne, |-----|-------| sur la deuxième, puis une ligne | valeur | valeur | par enregistrement. Les tirets doivent seulement être présents, pas alignés sur le texte. Pour contrôler l'alignement des colonnes, ajoutez deux-points à la ligne de séparation : |:---| à gauche, |:--:| au centre et |---:| à droite. Ainsi une ligne comme |:--|:-:|--:| donne des colonnes à gauche, au centre et à droite. Les barres extérieures ne sont pas obligatoires, mais elles rendent le code plus facile à lire et à copier. Si une cellule doit contenir une barre verticale littérale, échappez-la avec un antislash sous la forme \| pour que le parseur ne la prenne pas pour un séparateur de colonne ; c'est le piège le plus courant quand on met du code ou une regex dans une cellule. Les tableaux sont une extension GFM, donc GitHub, GitLab et Obsidian les rendent, mais le CommonMark strict non.

Comment ajouter un saut de ligne en Markdown ?

Markdown propose trois façons de forcer un saut de ligne à l'intérieur d'un paragraphe. La méthode classique consiste à terminer la ligne par deux espaces finaux puis à appuyer sur Entrée ; le souci, c'est que l'espace final est invisible et que de nombreux éditeurs le suppriment automatiquement. La méthode GFM la plus fiable est un antislash en fin de ligne, qui est visible dans le code et survit au nettoyage des espaces. La troisième voie est la balise HTML <br>, qui fonctionne dans pratiquement tous les rendus, y compris le CommonMark strict. Pour démarrer un tout nouveau paragraphe plutôt qu'un saut doux, laissez simplement une ligne entièrement vide entre les deux blocs de texte ; c'est le séparateur le plus portable de tous et celui que vous voudrez la plupart du temps.

Quelles fonctions Markdown marchent sur GitHub, GitLab et CommonMark ?

Cela dépend de la construction, et c'est précisément ce qu'indiquent les badges de compatibilité de chaque carte. Gras, italique, titres, liens, images, citations, listes et code clôturé sont du CommonMark de base et s'affichent à l'identique partout. Tableaux, listes de tâches, barré et autoliens d'URL nue sont des extensions GFM : GitHub, GitLab et Obsidian les prennent en charge, mais le CommonMark strict non. Les notes de bas de page et la math TeX/LaTeX s'affichent sur GitHub, GitLab et Obsidian mais pas en CommonMark pur. Les encadrés GitHub (> [!NOTE]) fonctionnent sur GitHub, GitLab et Obsidian (Obsidian a des encadrés natifs) mais se dégradent en simple citation ailleurs. Les @mentions et références #issue sont spécifiques à GitHub. Les listes de définitions (terme / : définition) sont une fonction de Markdown Extra / pandoc et ne s'affichent sur aucune des quatre. Pour des documents qui doivent survivre à n'importe quel pipeline, activez "Portable seulement" pour filtrer la fiche jusqu'au sous-ensemble sûr en CommonMark.

Pourquoi cet aide-mémoire se charge-t-il bien plus vite que d'autres sites de documentation ?

Trois raisons. D'abord, chaque carte est rendue côté serveur en HTML statique ; pas de parseur Markdown côté client à attendre, pas de bundles Mermaid, pas de JavaScript de coloration syntaxique - les octets que vous voyez sont les octets envoyés par le serveur. Ensuite, la recherche utilise un filtre vanilla avec querySelectorAll sur quelques dizaines de cartes, donc même sur un téléphone modeste, chaque frappe met à jour le DOM en moins d'une milliseconde. Enfin, la page est mise en cache de manière agressive par l'infrastructure WuTools : HTML 10 jours, le petit JS du filtre un an, et les icônes SVG aussi. Une fois la page en cache, l'aide-mémoire apparaît dans le temps que met le navigateur à dessiner une image.