CommonMark : une spécification formelle pour Markdown

CommonMark est une version rationalisée de la syntaxe Markdown avec une spécification dont le but est de supprimer les ambiguïtés et les incohérences entourant la spécification Markdown originale. Il offre une spécification standardisée qui définit la syntaxe commune du langage ainsi qu'une suite de tests complets pour valider les implémentations Markdown par rapport à cette spécification.

GitHub utilise Markdown comme langage de balisage pour son contenu utilisateur.

"CommonMark est un projet ambitieux visant à spécifier formellement la syntaxe Markdown utilisée par de nombreux sites Web sur Internet d'une manière qui reflète son utilisation dans le monde réel [...] Il permet aux gens de continuer à utiliser Markdown de la même manière qu'ils l'ont toujours fait tout en offrant aux développeurs une spécification complète et des implémentations de référence pour interagir et afficher Markdown de manière cohérente entre les plates-formes.

- "Une spécification formelle pour GitHub Flavored Markdown", Le blog GitHub

En 2012, GitHub a créé sa propre version de Markdown - GitHub Flavored Markdown (GFM) - pour lutter contre le manque de standardisation de Markdown et étendre la syntaxe à ses besoins. GFM a été construit au-dessus de Sundown, un analyseur spécifiquement conçu par GitHub pour résoudre certaines des lacunes des analyseurs Markdown existants à l'époque. Cinq ans après, en 2017, il a annoncé l'abandon de Sundown au profit de la bibliothèque d'analyse et de rendu CommonMark, cmark dans Une spécification formelle pour GitHub Flavored Markdown.

Dans la section Questions courantes de Markdown et Visual Studio Code, il est documenté que Markdown dans VSCode cible la spécification CommonMark Markdown à l'aide de la bibliothèque markdown-it, qui elle-même suit la spécification CommonMark.

CommonMark a été largement adopté et implémenté (voir la liste des implémentations de CommonMark) pour une utilisation dans différents langages comme C (par exemple cmark), C# (par exemple CommonMark.NET), JavaScript (par exemple markdown-it) etc. C'est une bonne nouvelle en tant que développeurs et les auteurs se déplacent progressivement vers une nouvelle frontière de pouvoir utiliser Markdown avec une syntaxe cohérente et une spécification standardisée.

Une brève note sur les analyseurs Markdown

Les analyseurs Markdown sont au cœur de la conversion du texte Markdown en HTML, directement ou indirectement.

Les analyseurs comme cmark et commonmark.js ne convertissent pas directement Markdown en HTML, mais le convertissent en arbre de syntaxe abstraite (AST), puis restituent l'AST en HTML, ce qui rend le processus plus granulaire et sujet à manipulation. Entre l'analyse - vers AST - et le rendu - vers HTML - par exemple, le texte Markdown pourrait être étendu.

Prise en charge de la syntaxe Markdown de CommonMark

Les projets ou plates-formes qui implémentent déjà la spécification CommonMark comme base de leur saveur spécifique sont souvent un sur- ensemble du sous- ensemble strict de la spécification CommonMark Markdown. Pour l'essentiel, CommonMark a atténué de nombreuses ambiguïtés en créant une spécification conçue pour être construite. GFM en est un excellent exemple, bien qu'il prenne en charge toutes les syntaxes CommonMark, il l'étend également en fonction de son utilisation.

La prise en charge de la syntaxe de CommonMark peut être limitée au début, par exemple, elle ne prend pas en charge cette syntaxe de table, mais il est important de savoir que c'est par conception comme le révèle ce commentaire dans ce fil de conversation : que la syntaxe prise en charge est stricte et a déclaré être la syntaxe de base du langage lui-même - la même que celle spécifiée par son créateur, John Gruber dans Markdown: Syntax.

Au moment de la rédaction, voici un certain nombre de syntaxes prises en charge :

1. Paragraphes et sauts de ligne,
2. En-têtes,
3. Emphase et emphase forte,
4. Règles horizontales,
5. Listes,
6. Liens,
7. Images,
8. Citations en bloc,
9. Code,
10. Blocs de codes.

Pour suivre les exemples, il est conseillé d'utiliser l'éditeur dingus commonmark.js pour essayer la syntaxe et obtenir l'aperçu rendu, le HTML généré et l'AST.

Paragraphes et sauts de ligne

Dans Markdown, les paragraphes sont des lignes continues de texte séparées par au moins une ligne blanche.

Les règles suivantes définissent un paragraphe :

1. Les paragraphes Markdown sont rendus en HTML sous la forme de l'élément Paragraph, <p>.
2. Les différents paragraphes sont séparés par une ou plusieurs lignes vides entre eux.
3. Pour un saut de ligne, un paragraphe doit être post-fixé avec deux espaces vides (ou son équivalent de tabulation), ou une barre oblique inverse ( \ ).

• Tutoriel interactif pour en savoir plus sur les paragraphes.
• Dingus permalink consultez l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les paragraphes.

Rubriques

Les en-têtes dans Markdown représentent l'un des éléments d'en-tête HTML. Il existe deux manières de définir les en-têtes :

1. Cap ATX.
2. En-tête Setext.

Les règles suivantes définissent les en-têtes ATX :

1. Le niveau de titre 1 ( h1 ), jusqu'au niveau de titre 6, ( h6 ) sont pris en charge.
2. Les titres de style Atx sont précédés du symbole dièse ( # ).
3. Il doit y avoir au moins un espace vide séparant le texte et le symbole dièse ( # ).
4. Le nombre de hachages est équivalent au nombre cardinal de l'en-tête. Un hachage est h1 , deux hachages, h2 , 6 hachages, h6 .
5. Il est également possible d'ajouter un nombre arbitraire de symboles de hachage aux en-têtes, bien que cela n'ait aucun effet (c'est-à-dire # Heading 1 # )

Les règles suivantes définissent les en-têtes Setext :

1. Seuls le niveau de titre 1 (h1) et le niveau de titre 2 (h2) sont pris en charge.
2. La définition de style Setext se fait avec les symboles égal (=) et tiret respectivement.
3. Avec Setext, au moins un symbole égal ou tiret est requis.

• Tutoriel interactif pour en savoir plus sur les en-têtes.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les en-têtes ATX.
• En savoir plus sur les en-têtes Setext.

Emphase et emphase forte

L'emphase dans Markdown peut être en italique ou en gras (emphase forte).

Les règles suivantes définissent l'emphase :

1. L'emphase ordinaire et forte sont rendues en HTML sous la forme de l'élément Emphasis, <em>, et Strong, <strong>, respectivement.
2. Un texte délimité par un seul astérisque ( * ) ou trait de soulignement ( _ ) sera un accent.
3. Un texte délimité par des astérisques doubles ou un trait de soulignement mettra fortement l'accent.
4. Les symboles de délimitation (astérisques ou trait de soulignement) doivent correspondre.
5. Il ne doit pas y avoir d'espace entre les symboles et le texte joint.

• Tutoriel interactif pour en savoir plus sur l'emphase.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur l'emphase et l'emphase forte.

Règle horizontale

Une règle horizontale, <hr/> est créée avec au moins trois astérisques ( * ), traits d'union ( - ) ou traits de soulignement ( _ ), sur une nouvelle ligne. Les symboles sont séparés par n'importe quel nombre d'espaces, ou pas du tout.

• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les pauses thématiques.

Listes

Les listes dans Markdown sont soit une liste à puces (non ordonnée), soit une liste ordonnée.

Les règles suivantes définissent une liste :

1. Les listes à puces sont rendues en HTML sous la forme de l'élément de liste non ordonné, <ul>.
2. Les listes ordonnées sont rendues en HTML sous la forme de l'élément de liste ordonnée, <ol>.
3. Les listes à puces utilisent des astérisques, des signes plus et des traits d'union comme marqueurs.
4. Les listes ordonnées utilisent des nombres suivis de points ou de parenthèses fermantes.
5. Les marqueurs doivent être cohérents (vous ne devez utiliser que le marqueur avec lequel vous commencez pour le reste de la définition des éléments de la liste).

• Tutoriel interactif pour en savoir plus sur les listes.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les éléments de listes.

Liens

Les liens sont pris en charge avec le format en ligne et de référence .

Les règles suivantes définissent un lien :

1. Les liens sont rendus sous la forme de l'élément HTML Anchor, <a>.
2. Le format en ligne a la syntaxe : [value](URL "optional-title") sans espace entre les crochets.
3. Le format de référence a la syntaxe : [value][id] pour la référence, et [id]: href "optional-title" pour l'étiquette du lien hypertexte, séparés par au moins une ligne.
4. L' id est l' identificateur de définition et peut être composé de lettres, de chiffres, d'espaces et de signes de ponctuation.
5. Les identificateurs de définition ne sont pas sensibles à la casse.
6. Il existe également une prise en charge des liens automatiques, où l'URL est délimitée par le symbole inférieur à (<) et supérieur à (>) et affichée littéralement.

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• Tutoriel interactif pour en savoir plus sur les liens.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les liens.

Images

Les images dans Markdown suivent les formats en ligne et de référence pour les liens.

Les règles suivantes définissent les images :

1. Les images sont rendues sous la forme de l'élément d'image HTML, <img>.
2. Le format en ligne a la syntaxe : ![alt text](image-url "optional-title") .
3. Le format de référence a la syntaxe : ![alt text][id] pour la référence, et [id]: image-url "optional-title" pour l'étiquette de l'image. Les deux doivent être séparés par au moins une ligne blanche.
4. Le titre de l'image est facultatif et l'URL de l'image peut être relative.

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• Tutoriel interactif pour en savoir plus sur les images.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur Images.

Citations en bloc

L'élément HTML Block Quotation, <blockquote>, peut être créé en préfixant une nouvelle ligne avec le symbole supérieur à ( > ).

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

Les blocs de citations peuvent être imbriqués :

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

Ils peuvent également contenir d'autres éléments Markdown, tels que des en-têtes, du code, des éléments de liste, etc.

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• Tutoriel interactif pour en savoir plus sur les blocs de citations.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les Blockquotes.

Code

L'élément HTML Inline Code, <code>, est également pris en charge. Pour en créer un, délimitez le texte avec des back-ticks (`), ou des doubles back-ticks s'il doit y avoir un back-tic littéral dans le texte englobant.

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• Tutoriel interactif pour en savoir plus sur le code.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les étendues de code.

Blocs de code

L'élément HTML Preformatted Text, <pre>, est également pris en charge. Cela peut être fait avec au moins trois et un nombre égal de back-ticks de délimitation ( ` ), ou tildes ( ~ ) - normalement appelés code-fence, ou une nouvelle ligne commençant par une indentation d'au moins 4 espaces.

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• Tutoriel interactif pour en savoir plus sur le code.
• Permalien Dingus pour consulter l'exemple complet avec l'aperçu et l'AST.
• En savoir plus sur les blocs de code clôturés et indentés.

Utilisation du HTML en ligne

Selon la note de spécification originale de John Grubers sur le HTML en ligne, tout balisage qui n'est pas couvert par la syntaxe de Markdown, vous utilisez simplement le HTML lui-même, avec les seules restrictions sont que les éléments HTML au niveau du bloc - par exemple <div> , <table> , <pre> , <p> , etc. — doivent être séparés du contenu environnant par des lignes vides, et les balises de début et de fin du bloc ne doivent pas être en retrait avec des tabulations ou des espaces.

Cependant, à moins que vous ne soyez probablement l'une des personnes derrière CommonMark lui-même, ou à peu près, vous écrirez très probablement Markdown avec une version déjà étendue pour gérer un grand nombre de syntaxes non actuellement prises en charge par CommonMark.

Aller de l'avant

CommonMark est un travail constant en cours avec ses spécifications mises à jour pour la dernière fois le 6 avril 2019. Il existe un certain nombre d'applications populaires qui le prennent en charge dans le pool d'outils Markdown. Avec la prise de conscience de l'effort de CommonMark vers la normalisation, je pense qu'il suffit de conclure que dans la simplicité de Markdown, il y a beaucoup de travail en cours dans les coulisses et que c'est une bonne chose pour l'effort de CommonMark que la spécification formelle de GitHub Flavored Markdown est basé sur le cahier des charges.

L'évolution vers l'effort de normalisation de CommonMark n'empêche pas la création de saveurs pour étendre sa syntaxe prise en charge, et alors que CommonMark se prépare pour la version 1.0 avec des problèmes qui doivent être résolus, il existe des ressources intéressantes sur l'effort continu que vous pouvez utiliser pour votre lecture.

Ressources

• Présentation de Markdown par John Gruber
• Site officiel de Common Mark
• Spécification de Markdown à saveur GitHub
• dépôt officiel cmark
• Le fork de cmark de GitHub
• Markdown sur Wikipédia
• Guide de démarque