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.

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.