Fermer

décembre 3, 2020

Une spécification formelle pour Markdown


À propos de l'auteur

Adebiyi Adedotun Lukman est un ingénieur UI / Frontend basé à Lagos, au Nigeria, qui adore également UI / UX Design pour l'amour des grands logiciels. Quand …
En savoir plus sur
Adebiyi

Markdown est un puissant langage de balisage qui permet l'édition et la mise en forme au format texte brut qui peut ensuite être analysé et rendu au format HTML. Il a une syntaxe déclarative à la fois puissante et facile à apprendre pour les techniciens et non techniques. Cependant, en raison des ambiguïtés consécutives dans sa spécification originale, il y a eu un certain nombre de saveurs distinctes (ou versions personnalisées) qui visent à effacer ces ambiguïtés ainsi qu'à étendre le support de la syntaxe d'origine. Cela a conduit à une forte divergence entre ce qui peut être analysé et ce qui est rendu. CommonMark vise à fournir une spécification standardisée de Markdown qui reflète son utilisation dans le monde réel.

CommonMark est une version rationalisée de la syntaxe Markdown avec une spécification dont le but est d'éliminer les ambiguïtés et les incohérences entourant la spécification Markdown originale. Il offre une spécification normalisée qui définit la syntaxe commune du langage ainsi qu'une suite de tests complets pour valider les implémentations de 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. »

A Formal Spec For GitHub Flavored Markdown »Le blog GitHub

En 2012, GitHub a créé sa propre saveur de Markdown – GitHub Flavored Markdown (GFM) – pour lutter contre le manque de standardisation Markdown et étendre la syntaxe à ses besoins. GFM a été construit sur Sundown un analyseur spécialement construit par GitHub pour résoudre certaines des lacunes des analyseurs Markdown existants à l'époque. Cinq ans après, en 2017, il a annoncé la dépréciation de Sundown en faveur de la bibliothèque d'analyse et de rendu CommonMark, cmark dans Une spécification formelle pour GitHub Flavored Markdown .

Dans le Common Questions section of Markdown and Visual Studio Code il est documenté que Markdown dans VSCode cible la spécification CommonMark Markdown en utilisant la bibliothèque markdown-it qui en elle-même suit

CommonMark a été largement adopté et mis en œuvre (voir la List of CommonMark Implementation ) 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 car les 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 normalisée.

A Note courte 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 Markdown en HTML directement, à la place, ils le convertissent en Abstract Syntax Tree (AST) puis rendent l'AST au format HTML, rendant 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.

CommonMark's Markdown Syntax Support

Projets ou plates-formes qui implémentent déjà la spécification CommonMark en tant que les références de leur saveur spécifique sont souvent le 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 est un excellent exemple, bien qu'il prenne en charge toutes les syntaxes CommonMark, il l'étend également en fonction de son utilisation.

Le support de la syntaxe de CommonMark peut être limité au début, par exemple, il ne prend pas en charge cette syntaxe de table mais il est important de savoir que c'est par conception car ce commentaire dans ce fil de conversation révèle: que la syntaxe supportée est stricte et dit ê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 de cet article, Voici un certain nombre de syntaxes prises en charge:

  1. Paragraphes and Line Breaks,
  2. Headers,
  3. Emphasis and Strong Emphasis,
  4. Horizontal Rules,
  5. Lists,
  6. Links,
  7. Images,
  8. Blockquotes,
  9. Code,
  10. Code Blocks.

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

Paragraphes And Line Breaks

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

Les règles suivantes définissent un paragraphe:

  1. Les paragraphes de démarque sont rendus en HTML comme l'élément Paragraph,

    .
  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-fixe avec deux espaces vides (ou son équivalent de tabulation), ou une barre oblique inverse ( ).
Syntaxe Rendered HTML
Ceci est une ligne de texte

Ceci est une ligne de texte

Ceci est une ligne de texte
Et une autre ligne de texte
Et une autre mais le
même paragraphe

] Ceci est une ligne de texte
Et une autre ligne de texte
Et un autre mais le
même paragraphe

Ceci est un paragraphe

Et un autre paragraphe

Et un autre

Ceci est un paragraphe

Et un autre paragraphe

Et un autre

Deux espaces après une ligne de texte
Ou un barre oblique inverse post-fixe
Les deux signifient un saut de ligne

Deux espaces après une ligne de texte

Ou une barre oblique inverse post-fixe

Les deux signifient un saut de ligne

En-têtes

En-têtes dans Markdown représente l'un des éléments HTML Heading . Il existe deux façons de définir les en-têtes:

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

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

  1. En-tête de niveau 1 ( h1 ), jusqu'au niveau de titre 6, ( h6 ) sont pris en charge.
  2. Les en-têtes 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 de hachage ( # ).
  4. Le nombre de hachages équivaut 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 (s ) aux en-têtes, bien que cela n'ait aucun effet (par exemple # Titre 1 # )
Syntaxe HTML rendu
# Titre 1

Titre 1

## Titre 2

Titre 2

### Titre 3

Titre 3

#### Titre 4

Titre 4

##### Titre 5
Titre 5 [19659073] ###### Titre 6
Titre 6
## Titre 2 ##

Titre 2

Les règles suivantes définissent les titres Setext :

  1. Titre uniquement le niveau 1 (h1) et le niveau de titre 2, (h2) sont pris en charge.
  2. La définition de style Setext se fait respectivement avec les symboles égal (=) et tiret.
  3. Avec Setext, au moins un symbole égal ou tiret est obligatoire.
Syntaxe HTML rendu
Heading 1
= [19659064] Rubrique 1
Rubrique 2

Rubrique 2

Emphase et emphase forte

L'insistance dans Markdown peut être soit en italique, soit en gras (emphase forte).

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

  1. L'accentuation ordinaire et forte est rendue en HTML par les éléments Emphasis, et Strong, respectivement.
  2. Un texte délimité par un seul astérisque ( * ) ou un trait de soulignement ( _ ) sera mis en évidence.
  3. Un texte délimité par un double astérisque ou un trait de soulignement sera fortement accentué.
  4. Les symboles de délimitation (astérisques ou tiret bas) doivent match.
  5. Il ne doit y avoir aucun espace entre les symboles et le texte joint.
Syntaxe HTML rendu
_Italic_ Italic
* Italic * Italic [19659101] __ Gras __ Italique
** Gras ** Italique

Règle horizontale

A Règle horizontale,


est crea ted avec trois astérisques ou plus ( * ), des tirets ( - ) ou des traits de soulignement ( _ ), sur une nouvelle ligne. Les symboles sont séparés par un nombre quelconque d'espaces, ou pas du tout.

Syntaxe HTML rendu
***
* * *
---
- - -
___
_ _ _

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ée,
      .
    • Les listes ordonnées sont rendues au format HTML sous la forme de l'élément de liste ordonnée
        .
      1. Les listes à puces utilisent des astérisques, des plus et des tirets comme marqueurs.
      2. Les listes ordonnées utilisent des nombres suivis de points ou de parenthèses fermantes.
      3. Les marqueurs doivent être cohérents (vous ne devez utiliser que le marqueur par lequel vous commencez pour le reste de la définition des éléments de la liste).
      Syntaxe [19659037] HTML rendu
      * un
      * deux
      * trois
      • un
      • deux
      • trois
      + un
      + deux
      + trois
      • un [19659132] deux
      • trois
      – un
      – deux
      – trois
      • un
      • deux
      • trois
      – un
      – deux
      + trois [19659131] un

    • deux
      • trois
      1. un
      2. deux
      3. trois
      1. un
      2. deux
      3. trois
      1. trois
      2. quatre
      3. cinq
      1. trois
      2. quatre
      3. cinq
      1. un
      100. deux
      3. trois
      1. un
      2. deux
      3. trois

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

      Les règles suivantes définissent un link:

      1. Les liens sont rendus sous la forme de l'élément HTML Anchor, .
      2. Le format inline 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 le libellé du lien hypertexte, séparés par au moins une ligne .
      4. L'identifiant est l'identificateur de définition et peut être composé de lettres, de chiffres, d'espaces et de ponctuation.
      5. Les identificateurs de définition ne sont pas sensibles à la casse.
      6. Il y a prend également en charge les liens automatiques, où l'URL est délimitée par le symbole inférieur à () et affichée littéralement.
      
      [Google] (https://google.com "Google")
      
       Google 
      
      
      [Google] (https://google.com)
      
       Google 
      
      
      [Article] (/ 2020/09 / compare-styling-methods-next-js)
      
       Comparaison des méthodes de style dans Next.js 
      
      
      [Google] [id]
      
      
      
      HTML rendu:  Google 
      
      
      
      
       google.com 
      
      
      
      
       mark@google.com 

      Images

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

      Ce qui suit les règles définissent les images:

      1. Les images sont rendues comme l'élément d'image HTML .
      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 d'image. Les deux doivent être séparés par au moins une ligne vide.
      4. Le titre de l'image est facultatif et l'url de l'image peut être relative.
      
      ! [alt text] (image-url "optional-title")
      
       texte alternatif 
      
      
      ! [alt text] [id]
      
      
      
      
       texte alternatif 

      Blockquotes

      L'élément HTML Block Quotation,

      peut être créé en préfixant une nouvelle ligne avec le symbole supérieur à (> ). [19659197]> Ceci est un élément blockquote
      > Vous pouvez démarrer chaque nouvelle ligne
      > avec le symbole supérieur à.
      > Cela vous donne un meilleur contrôle
      > sur ce qui sera rendu.

      Ceci est un élément blockquote
      Vous pouvez commencer chaque nouvelle ligne
      avec le symbole supérieur à.
      Cela vous donne un plus grand contrôle
      sur ce qui sera rendu.

      Les blockquotes peuvent être imbriqués:

      
      > Blockquote avec un paragraphe
      >> Et un autre paragraphe
      >>> Et un autre
      
      
      

      Blockquote avec un paragraphe

      Et un autre paragraphe

      Et un autre

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

      
      > Blockquote with a paragraph
      > # Titre 1
      > Titre 2
      > -
      > 1. Un
      > 2. Deux
      
      
      

      Citation de bloc avec un paragraphe

      Titre 1

      Titre 2

      1. Un
      2. Deux

      Code

      L'élément HTML Inline Code, est également pris en charge. Pour en créer un, délimitez le texte par des contre-graduations (`), ou des doubles contre-graduations s'il doit y avoir une contre-graduation littérale dans le texte englobant.

      
      ` inline code snippet`
      
       extrait de code en ligne 
      
      
       ``
      
        
      
      
       `` Il y a un back-tick en ligne (`). ''
      
       Il y a un back-tick en ligne (`). 

      Code Blocks

      L'élément HTML Preformatted Text,

      est également pris en charge. Cela peut être fait avec au moins trois et un nombre égal de contre-graduations de délimitation ( `), ou tildes ( ~ ) - normalement appelées une clôture de code, ou un nouvelle ligne commençant par une indentation d'au moins 4 espaces. 
      
       ''
      const dedupe = (tableau) => [...new Set(array)];
      ''
      
      
       const dedupe = (tableau) => [...new Set(array)]; 


      const dedupe = (tableau) => [...new Set(array)];

       const dedupe = (array) => [...new Set(array)]; 

      Utilisation du HTML en ligne

      D'après la note de spécification originale de John Grubers sur le HTML en ligne tout balisage non couvert par la syntaxe de Markdown, vous utilisez simplement HTML lui-même, avec Les seules restrictions sont que les éléments HTML au niveau du bloc - par exemple

      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 indentées 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 allez probablement écrire Markdown avec une saveur 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 sa spécification pour la dernière fois mise à jour le 6 avril 2019 . Il existe un certain nombre d'applications populaires qui le supportent dans le pool des outils Markdown . Compte tenu 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 coulisse et que c'est une bonne chose pour l'effort de CommonMark que la spécification formelle de GitHub Flavored Markdown est basé sur la spécification .

      L'évolution vers l'effort de standardisation CommonMark n'empêche pas la création de saveurs pour étendre sa syntaxe supportée, et comme 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.

      Resources

       Smashing Editorial (ks, ra, yk, il)




      Source link