Nicolas Bages homo-numericus depuis 1986

Qu'est ce que le Markdown ?

Contenu

Le markdown est devenu en quelques années le markup language favoris des développeurs. Ils l'utilisent souvent et partout. Petit à petit, ce format est aussi entré dans les usages de certains rédacteurs et même de chercheurs.

Pour les autres, il reste encore incompris car, d'apparence, il ne fait que complexifier un fichier texte.

Qu'est ce que le Markdown ?

Quand on parle de Markdown de manière générale, on parle en fait de deux choses :

  1. le markup language léger qui sert à formater des éléments à partir de texte simple créé en 2004 par John Gruber
  2. un interpréteur qui va convertir le texte simple en HTML

Le but de ce concept est de pouvoir écrire et maintenir du contenu dans un format aussi simple à utiliser et à lire que possible.

Une fois écris, sa finalitée du markdown est une conversion en HTML puis publié. Ceci explique pourquoi il a d'abord été utilisé par des développeurs alors qu'il est d'abord destination des rédacteurs sans connaissances techniques particulières.

Le markup

Les bases sont simple. Il s'agit d'écrire du texte et de le mettre en forme au fur et à mesure avec une syntaxe légère.

Exemple de markdown

### Qu'est ce que le Markdown ?

C'est un langage de balisage simple qui permet d'écrire du texte à destination de la lecture par un humain ou un interpréteur logiciel.

Chez [Weinto](https://www.weinto.com) nous utilisons markdown pour **toutes nos rédactions**.

- Techniques
- Wiki
- Blog

Beaucoup d'interpréteurs intègrent une coloration syntaxique du `code`.

``js
// file: index.js

const foo = 'bar'

export default foo;
``

Rendu HTML

<h3>
  Qu'est ce que le Markdown ?
</h3>
<p>
  C'est un langage de balisage simple qui permet d'écrire du texte à destination de la lecture par un humain ou un interpréteur logiciel.
</p>
<p>
  Chez <a href="https://www.weinto.com">Weinto</a> nous utilisons markdown pour <strong>toutes nos rédactions</strong>.
</p>
<ul>
  <li>
    Techniques
  </li>
  <li>
    Wiki
  </li>
  <li>
    Blog
  </li>
</ul>
<p>
  Beaucoup d'interpréteurs intègrent une coloration syntaxique du <code>code</code>.
</p>


<pre>
  <code class="language-javascript">// file: index.js

const foo = 'bar'

export default foo;
</code>
</pre>

Les interpréteurs

Les principaux sont :

  • MultiMarkdown
  • Github Flavored Markdown
  • Pandoc
  • CommonMark
  • Markdown Extra

On peut les retrouver dans plusieurs outils en ligne comme Gitlab et Github, Wiki.js, Wordpress. Chacuns avec des ajouts en fonction des besoins de leurs plateformes.

Plugins

Markdown accepte les plugins pour enrichir ses fonctionnalités et la syntaxe. On peut commencer par citer les feuilles de style CSS externes pour personnaliser le rendu. Le concept va plus loin avec l'élément code qui accepte un argument language, comme javascript dans l'exemple précédent.

  • Mermaid : pour faire des diagrammes
  • Mathjax : pour écrire des formules mathématiques au format LaTeX
  • Linguist : pour la coloration syntaxique des blocs de code

Il en existe évidement beaucoup d'autres, disponibles dans plusieurs langages (Go, JS, PHP, Java...) en fonction de vos besoins.

Les éditeurs

En tant que développeur j'ai longtemps utilisé Sublime Text pour écrire du markdown puis je suis passé assez naturellement à VSCode et son mode preview pour rédiger de la documentation technique.

Zettlr devient petit à petit un éditeur intéressant lorsqu'il s'agit de rédiger de longs papiers. Je reste quand même avec VSCode par confort pour mon Wiki privé (Wiki.js) ou mes notes avec une synchronisation basée sur Git. Ce blog est entièrement basé sur du Markdown :)

MacDown n'est jamais très loin quand j'ai besoin d'ouvrir un simple fichier .md.

Un mot sur le standard

Markdown a fait l'objet d'une spécification informelle puis il y a eu un référentiel d'implémentation pour sa conversion en HTML. Avec le temps, beaucoup d'acteurs ont créé leurs propres implémentations en fonction de leurs besoins. La majorité a simplement souhaité ajouter des fonctionnalités par dessus la syntaxe de base.

Cela a posé problème tant dans la rédaction que dans l'interprétation de markdown. Chaque convertisseur utilisait une implémentation différente. Le rendu final (HTML) dépend de l'implémentation alors on peut vite imaginer qu'un document ne puisse pas fournir le même rendu d'un logiciel à un autre.

Vous pouvez consulter Babelmark3 pour observer les différentes implémentations de markdown référencés par Babelmark-registry.

Ce n'est qu'en 2016 que les RFC 7763 et RFC 7764 ont été publié. La RFC 7763 a d'ailleurs introduit le MIME type text/markdown alors que la RFC 7764 introduit les variantes de MultiMarkdown, Github Flavored Markdown, Pandoc, CommonMark, Markdown Extra et Fountain.io

Avec elles sont arrivées :

  • les metadatas
    • title et subtitle
    • keywords
    • author
    • web : l'URL de l'auteur
    • date
    • copyright
    • email
    • css : un CSS qui permet de personnaliser le rendu
    • format : complete pour un rendu XHTML complet avec le header ousnippet sans header, pratique pour publier sur un site web par exemple
    • language
    • revision
  • les notes de bas de page
  • les tableaux
  • la coloration syntaxique du code

Il y a bien plus d'éléments que ça. Je vous invite à lire les RFC ou les éléments de bases. Les autres éléments ou langages dépendent des interpréteurs utilisés.

Sécurité

Vous l'avez compris, le markdown est converti en HTML. Cela ne va pas sans poser quelques problèmes de sécurité notamment concernant le XSS 1.

Les attaques XSS sont utilisées pour obtenir un accès aux informations privées des utilisateurs. Markdown n'a pas de faille de sécurité XSS en lui même mais le moteur de conversion, lui, peut être détourné dès lors qu'il autorise l'utilisation du HTML directement dans le markdown.

Exemple :

[Foo Bar](#foo-bar)

Ceci va créer le code HTML suivant

<p>
  <a href="#foo-bar">Foo Bar</a>
</p>

Rien de méchant, c'est une ancre HTML.

Maintenant modifions le markdown en y introduisant du HTML :

[John Doe](javascript:alert('xss1'))

<a name="n" href="javascript:alert('xss2')">Foo Bar</a>

<script>
  alert('xss3')
</script>

Ceci va créer le HTML suivant :

<p>
  <a href="javascript:alert('xss1')">John Doe</a>
</p>

<p>
  <a name="n" href="javascript:alert('xss2')">Foo Bar</a>
</p>

<script>
  alert('xss3')
</script>

Le lien markdown sera converti en HTML et le reste sera rendu tel quel avec du JavaScript malicieux.

Deux étapes sont nécessaires pour se protéger :

  1. Désactiver le HTML dans Markdown si votre convertisseur le propose
  2. Il est très important de vérifier ce que le convertisseur génère car markdown ne filtre rien, il ne fait que donner une URL

Il existe des filtres comme kses (PHP) utilisé par Wordpress qui passent après la génération pour supprimer les éléments HTML indésirables.

  1. cross-site scripting↩