Pourquoi j’écris en Markdown

Mais c’est quoi Markdown ?

«A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.» (John Gruber)

Le Markdown est un langage de balisage léger. Imaginé au début des années 2000 pour distinguer la structure sémantique (titres, sous-titres, paragraphes, …) et la mise en forme d’un document, MD (pour les intimes) permet de produire des contenus éditoriaux dont le code est facilement compréhensible par un humain^[1].

Inspiré par la structuration des emails en « texte plein », Markdown est un langage facile à lire, sans tags étranges ni balises originales.

De plus, et cela sera un point important pour la suite, MD est facilement convertible en XHTML (ou HTML)^[2].

Markdown, vous l’avez probablement déjà rencontré sans le savoir, même dans des applications à grand succès comme WhatsApp et Hangout ou encore dans les commentaires YouTube.

Pourquoi j’utilise Markdown ?

Le positionnement

Dans une optique de libération des individus des technologies qu’ils utilisent, et en vue d’améliorer leur compréhension de ces mêmes outils, indispensables à une vraie libération, MD semble être un point d’entrée intéressant.

La dynamique de travail collaboratif que j’ai rencontré dans Cité Libre a amené la recherche d’outils et de formats de fichiers pour que les membres de l’équipe puissent produire du contenu ensemble. Articulé autour d’un dépôt Git, notre workflow (imaginé par Pierre) s’est naturellement orienté vers Markdown, à la façon de très nombreux développeurs qui optent pour ce langage afin de publier leur documentation. Cette dernière est ainsi facilement lisible et accessible au travers d’un rendu interprété en html.

Les technologies ne doivent pas être des boîtes noires magiques mais des outils dont nous percevons, à minima, le fonctionnement, et dont les algorithmes mis en œuvre sont accessibles à tous.

La notion d’appropriation se révèle problématique en ce qui concerne les logiciels, surtout lorsqu’ils sont dits propriétaires, c’est-à-dire lorsqu’ils nous privent de cette capacité. Notre usage quotidien des traitements de texte, dont nous avons appris à tirer le meilleur avec le temps, conduit à nous les rendre familiers, de telle sorte que nous pensons nous les être appropriés (JULIEN DEHUT, 2018)^[3]

Les mauvaises habitudes liées aux outils de traitement de texte

Dans son excellent article Markdown comme condition d’une norme de l’écriture numérique^[4] Antoine Fauchié fait un panorama de la situation actuelle dont l’un des mots majeurs, selon lui est le WYSIWYG (What You See Is What You Get, ou ce que vous voyez est ce que vous obtenez en français).
L’avènement du WYSIWYG s’est fait à une époque où l’essentiel de la documentation produite au travers de l’ordinateur avait une seule finalité : être imprimée sur papier. La force du dispositif est d’avoir une impression aussi fidèle que ce que l’utilisateur voit à l’écran. Cependant, avec les années, ce paradigme, avec la migration des habitudes de lecture vers l’écran au détriment de l’imprimé et à la multiplication des devices, est devenu caduc.

le mode WYSIWYG suppose que la façon dont nous mettons en forme un document devra être similaire partout, sans accepter qu’il puisse y avoir des différences : par exemple entre deux navigateurs web ; ou, dans le cas du livre numérique, entre deux dispositifs ou applications de lecture16 ; ou encore, dans le temps, en fonction des évolutions des standards ou des moteurs de rendu. (JULIEN DEHUT, 2018)

Les documents produits par les traitements de texte se révèlent fondamentalement inadaptés à cet horizon de la consultation qui n’est plus l’imprimerie, mais l’ordinateur. En la matière, un logiciel écrase la concurrence depuis des années : Microsoft Word^[5]. Comme ses camarades du secteur (Page, libre office, …) en plus de ne pas avoir abandonné le cadre rassurant de la page A4, et malgré l’apparente facilité induite par l’interface, la sémantique est un élément peu valorisé et souvent oublié. Mais « un texte en gras et en corps 24 ne sera pas un titre de niveau 2, à moins de qualifier ce texte sémantiquement« ^[4:1]. Résultat : un document lisible et compréhensible par l’humain, un contenu sans sens pour la machine.

Dans un univers plus proche de nous, l’éditeur visuel pour HTML (cms, ide,…), et ce, malgré de grand progrès ces dernières années dans la qualité du code produit, apporte encore trop souvent la confusion entre forme / sémantique. Pourtant, nous savons à quel point elle est importante pour tous les périphériques d’affiches, pour les systèmes d’aide aux déficients visuels et auditifs, ainsi qu’à nos moteurs de recherche préférés.

Sans Web sémantique, sans cette lisibilité fondamentale, Google, en tant que moteur de recherche serait aveugle, puisque pour être indexées, utilisées, diffusées, les données doivent être lisibles. Or, non seulement enregistrer un texte sous le format docx ne le rend pas lisible pour des yeux humains, pas plus que le format doc, ou le format odt ; mais plus encore, l’enregistrement d’un texte dans l’un de ces formats le rend même illisible pour toute autre chose que par un logiciel de traitement de texte. L’enregistrement d’un fichier dans ces formats, en compilant avec le texte toutes les informations relatives à la mise en page, le rend donc inutilisable dans le cadre de ce nouvel horizon de consultation que représente le Web. D’autant que les traitements de texte n’autorisent qu’un contrôle partiel sur la gestion des métadonnées qui sont pourtant un élément fondamental de ce Web sémantique. (JULIEN DEHUT, 2018)

Markdown : language pivot et normatif

Le document numérique est un contenu dont la structure est distincte de la mise en forme, et possédant une structure sémantique. Mardown répond à ces impératifs : syntaxe simple et intention sémantique. Malgré quelques manques dans la syntaxe d’origine (comme les notes de bas de page), on peut voir en MD un standard avec un tronc largement commun ouvrant l’écriture numérique à de nombreux horizons. On notera le bel effort de l’équipe de https://commonmark.org pour produire une syntaxe unifiée.

Markdown est un language pivot qui permet une écriture numérique de qualité et offre à ses utilisateurs la possibilité de diffuser le contenu rédigé en HTML, .doc, .docs, LateX, PDF, ePub …

Utiliser Markdown

Quand vous utilisez un traitement de texte, ce que vous tapez à l’écran subit directement les modifications de style que vous appliquez. Le résultat est donc ce que vous voyez en temps réel à l’écran (logique imprimerie). Produire un document en markdown se fait le plus souvent de façon différente au travers de 2 étapes : rédaction/structuration (au sein d’un logiciel d’écriture) et « compilation » vers un format de fichier offrant des options de lecture et de mise page (PDF pour l’impression et le desktop, HTML pour le desktop et le mobile avec mise en forme « liquide », ePub pour les liseuses et le mobile, format word / open office, …).

Comme évoqué plus tôt, même si le texte/code écrit en MD reste lisible par un humain, il n’en demeure pas moins dépourvu de mise en forme dans le sens de mise en page. Cependant pour les plus réfractaires, il existe des systèmes WYSIWYG pour Markdown (on n’est pas à un paradoxe près).

La syntaxe de base

Il ne vous faudra que quelques minutes pour vous familiariser avec la syntaxe^[6] de MD. A titre d’exemple :

# Titre de niveau 3

Oportunum est, ut arbitror, explanare nunc causam, quae ad exitium praecipitem Aginatium inpulit iam inde a priscis maioribus nobilem, ut locuta est pertinacior fama. Nec enim super hoc ulla documentorum rata est fides.

## Titre de niveau 4

**Du Gras**, _de l'Italique_ [un lien](#) quem metuat, aut eum a quo se metui putet? Coluntur tamen simulatione dumtaxat ad tempus. Quod si forte, ut fit plerumque, ceciderunt, tum intellegitur quam fuerint inopes amicorum. Quod Tarquinium dixisse ferunt, tum exsulantem se intellexisse quos fidos amicos habuisset, quos infidos, cum iam neutris gratiam referre posset.

Sera interprété ainsi :

Titre de premier 3

Oportunum est, ut arbitror, explanare nunc causam, quae ad exitium praecipitem Aginatium inpulit iam inde a priscis maioribus nobilem, ut locuta est pertinacior fama. Nec enim super hoc ulla documentorum rata est fides.

Titre de niveau 4

Du Gras, de l’Italique un lien quem metuat, aut eum a quo se metui putet? Coluntur tamen simulatione dumtaxat ad tempus. Quod si forte, ut fit plerumque, ceciderunt, tum intellegitur quam fuerint inopes amicorum. Quod Tarquinium dixisse ferunt, tum exsulantem se intellexisse quos fidos amicos habuisset, quos infidos, cum iam neutris gratiam referre posset.

De l’écriture à la conversion

Les éditeurs plus ou moins WYSIWYG

Il y a plusieurs années, Mashable proposait une liste de 78 éditeurs pour Markdown^[7]. La situation n’a pas tellement changé et un grand nombre de solutions s’offre à vous pour vous adonner à votre nouvelle passion : écrire en MD. Vous pourriez vous limiter au bloc-notes standard de votre système d’exploitation, mais vous risqueriez de passer à côté de bien des facilités. Ci-dessous une sélection maison :

• Abricotine est un joli éditeur publié sous GPL-3. Export en html, coloration syntaxique basique, mode sombre, il ne lui manque presque rien, si ce n’est un menu visuel avec les principaux raccourcis et l’export en PDF. Attention cependant : la dernière version commence à dater. Disponible sur Windows / Linux / Mac.
• Stackedit vous permet d’écrire en MD au travers de votre navigateur web. Ecriture et visualisation en temps réel grâce à une interface coupée en 2. Il est possible de l’installer sur sa machine / serveur.
• Joplin est l’une des offres les plus complètes du monde open source. Synchronisation, rangement, chiffrement et interface efficace sont au programme. Il ne lui manque plus qu’un support natif des syntaxes MD étendues. Disponible sur Windows / Linux / Mac.

Dans l’univers des logiciels propriétaires on signalera le minimaliste et stylé Typora, le puissant MarkdownPad et le très sobre/multiplateformes iA. Si vous vous lancez dans la rédaction d’une thèse ou d’un long article, vous pourriez aimer Scrivener.

Sur des plateformes tout aussi fermées mais proposant une touche de collaboration on retiendra GitBook, HackMD, authorea et TrendMD.

Pour les plus aventureux d’entre vous, il existe Stylo une chaîne éditoriale « pour les sciences humaines et sociales^[8] » (je n’ai pas compris la licence utilisée sur le code, mais il est à parier que c’est du Creative Commons). Le code est disponible sur GitHub. Une vidéo des CRIHN 2018 présente l’outil.

Pour aller plus loin sur la question des éditeurs Markdown, je vous renvoie vers Le tango des éditeurs markdown de Christophe Masutti.

Les IDEs

Pour celles et ceux qui préfèrent se tourner vers un logiciel « pour les programmeurs », voici une sélection parmis la plétore de possibilités :

• Atom – Licence MIT and product by GitHub – Linux / Windows / Mac
• Brackets – Licence MIT – Linux / Windows / Mac
• Visual studio code – Licence MIT en version expat – Windows / Linux / Mac (l’exécutable semble utiliser une licence privateur)

La chaine éditoriale

Les difficultés de la conversion

Markdown en tant que langage interprété possédant une syntaxe évolutive (comme par exemple MultiMarkdown et GitHub Flavored Markdown), et évoluant dans un écosystème ouvert souffre de son principal avantage : la conversion.

Qui dit transformation dit norme. Et visiblement, chacun en fait à sa tête. Autant la structure générale du document sera respectée, autant de nombreuses surprises peuvent apparaître en fonction de l’outil que vous utiliserez :

• Possibilité de personnaliser la couleur, taille et police de votre texte
• Transformation correcte des caractères Unicode
• Conversion des smileys et emojis en image
• Gestion des notes de bas de page
• …

Et autant vous le dire sans plus de détours, atteindre le résultat que vous recherchez demandera très probablement un investissement temporel non négligeable.

Pour notre part, nous utilisons un IDE pour l’écriture, Pandoc pour la conversion en HTML et Wkhtmltopdf pour transformer le HTML, couplé à une feuille de style CSS en PDF.

Il faut reconnaître que la production des documents à partir du Markdown en conjonction de Pandoc demande dans un premier temps un certain investissement, en tout cas une motivation quotidienne, et peut-être quelque chose d’une résolution indéfectible. Cet investissement nous semble pourtant la contrepartie indispensable dont on doit s’acquitter dans le dessein de s’approprier, au sens de faire sien, ce qu’est devenu l’écrit dans notre société aujourd’hui. (JULIEN DEHUT, 2018)

Pandoc

Pandoc est un logiciel libre de conversion de documents numériques en ligne de commande développé par John MacFarlane en Haskell et publié sous licence GPL.^[9]

De base, la syntaxe de mise en œuvre de Pandoc est plutôt simple. Pour convertir votre fichier Markdown en PDF par exemple, rien de plus simple. On ouvre le terminal et on tape :

pandoc source.md -o sortie.pdf

Pandoc fait usage du langage LaTeX (un langage de rédaction de document plus complexe que MD, offrant plus de possibilités et qui est très utilisé dans le monde universitaire). Le rendu final est très académique. Travailler le rendu visuel de LaTex semble vraiment très complexe. Rien que pour ajouter une nouvelle famille de police … Avec l’installation de packages LaTeX j’ai réussi à utiliser la font que je voulais, mais le système ne gérait pas … le gras, l’italique et l’imbrication des 2. Parce que l’on ne peut pas tout faire de front, j’ai décidé de passer par Wkhtmltopdf (argument html5) via Pandoc pour transformer mon MD en HTML. J’y ai adjoint une feuille de style pour … styliser les différents éléments du texte. Même les fonts extérieures (google fonts, …) sont fonctionnelles. L’argument « –self-contained » permet d’écrire fonts et images directement dans le code HTML, pour faciliter le partage, sans avoir une multitude de fichiers à partager.

pandoc --self-contained -t html5 markdown-cite-libre.md -o markdown-cite-libre.html --css test.css

Wkhtmltopdf

Comme son nom l’indique, Wkhtmltopdf permet de transformer un fichier HTML en PDF. J’aurais pu l’utiliser directement « dans » Pandoc, mais certaines commandes m’étaient inaccessibles, comme l’édition du pied de page, la numérotation des feuillets, …

Pour faire marcher ce logiciel il m’a fallu rajouter, sous winddows, une variable d’environnement.

wkhtmltopdf --footer-center [page]/[topage] --footer-left "coucou à gauche" --footer-right "coucou à droite" --footer-font-size 8 --encoding 'UTF-8' markdown-cite-libre.html markdown-cite-libre.pdf

Conclusion

Markdown est un language léger. Sa prise en main est rapide, son usage sur les plateformes web est simple, sa conversion en pdf / html parfois complexe (annecdote : Pandoc réclame un saut de double saut de ligne entre un titre et un paragraphe. J’ai mis beaucoup de temps à comprendre le non rendu de titres, problèmes que je n’avais pas dans le rendu web de GitLab).

C’est un outil d’écriture. Il n’a pas été imaginé comme un outil de PAO. Pas d’espaces insécables, pas de positionnement fin des images, un rendu parfois variable (en fonction de l’outil utilisé), … A moins qu’il me faille un peu plus d’entraînement !

Il n’en demeure pas moins un magnifique objet, qui permet de se concentrer sur le texte, -et non sur la forme. Qui permet de repenser sa pratique d’écriture, de redonner du sens à la sémantique et de se détacher du paradigme de la feuille A4.

Il me reste encore du travail. Certains élements de rendu ne me conviennent pas encore : l’affichage des objets SVG est vraiment mauvais (mais pas tellement plus qu’avec des outils privateurs, comme la suite CC d’Adobe) et les smileys/emojis ne sont pas interprétés en images. Les caractères Unicode posent encore souvent problèmes. Problème également de priorité CSS pour les notes de bas de pages.

Et vous dans tout ça, comment produisez vous avec MD ?