Journal Le markdown, sous Emacs, et plus largement sous Linux

Sommaire

• Les éditeurs
  • Éditeurs de texte : les fondateurs
    • Emacs
    • Vim
  • Éditeurs de texte : les jeunes
    • Atom
    • Sublime
    • Brackets
  • Encore d'autres éditeurs
• L'export en HTML
• À propos de Android
• En guise de conclusion

La plupart d'entre vous connaissent le markdown, utilisé bien sûr ici même sur linuxfr, sur tant de forums, sur github ¹, un peu partout dans le monde. Il peut servir à créer une page web, écrire des méls, aux forums, aux pages de documentations, à prendre des notes, ou des bouquins. Même si vous ignoriez le nom vous connaissez donc un peu la syntaxe, comme cela :

> ce chevron sur un forum

> indique une ligne de commentaire, vous citez un gars puis le descendez.

Pour reprendre la présentation de son auteur, John Gruber ² le markdown est
1. une syntaxe permettant de formater du texte
2. un outil permettant de convertir du texte ainsi formaté en HTML (un script perl).

Il s'agit donc d'un language de markup, léger (language de balisage, semblent dire les kébékoués). Du markup mais moins léger ce serait par exemple XML ou HTML, justement.

Le markdown fut créé en 2004 ; le HTML datant de 97. Les deux définitions du markdown ont depuis connu des implémentations alternatives puisque 1. des variantes sont apparues quant à la syntaxe et 2. d'autres implémentations sont apparues. Cette page ³ présente différentes versions.

Je ne présenterai pas toutes les possibilités ici, mais en gros en markdown on peut formater (gras, italique), structurer (titres avec niveau), annoter (référence en bas de page). A priori rien d'extraordinaire donc, si ce n'est peut-être que la syntaxe est très lisible : écrire directement en markdown est plus que possible - simple ; même un homme politique y arriverait. Tout document markdown est valide ; il n'y a pas de syntaxerror en markdown. Dans la partie de Emacs je précise un peu de syntaxe.

Perso c'est le besoin de prise de note qui m'invite à m'y intéresser. La popularité du markdown fait qu'on peut trouver des éditeurs y compris libres sur toute plateforme (mobiles inclus) ; reste à synchroniser ces fichiers et voici le plus essentialiste logiciel de prise de note imaginable.

Si vous voulez une présentation de la syntaxe, en français, assez complète, il y a celle de Fabien Huet ici ⁴. Quant à cette dépêche, voyons les plus classiques editeurs, puis la question de l'export.

Les éditeurs

Éditeurs de texte : les fondateurs

Prenez un éditeur de texte centenaire, ajoutez une seule extension et roule ma poule.

Emacs

Cette première partie discute de l'implémentation de Markdown dans Emacs, et donc pas du protocole Markdown en soi. Bon cela dit ce sera l'occasion de détailler la syntaxe par comparaison avec un invité mystère.

Emacs possède un mode markdown, créée par Jason Blevins et dont la release initiale date de 2007⁵, qui permet de prévisualiser en live le formatage, et d'ajouter quelques commandes pour

• insérer des éléments mardown plus facilement,
• ou encore réoordoner les listes,
• naviguer dans les sections,
• réordoner les sections
• ou actionner un export en html, mais via un exporteur à préciser.

Je ne cite volontairement pas de raccourci clavier de ce mode ; d'une part les utilsateurs Emacs changent tous des milliards de choses, d'autre la doc de Jason Blevins explique la logique des raccourcis (bien entendus regroupés sous Control+c), donc lisez son truc les amis.

Ce mode dérive de outline-mode, qui est le mode créé en 1986 qui implémente la structuration via des titres, la navigation dans le document (de titre en titre), et la visibilité. Grâce à outline, on peut donc également jouer sur l'affichage : masquer tout sauf les titres, dérouler seulement le contenu du titre actuel, etc… On peut notamment se créer un buffer en read-only qui affiche un table des matières, et sert uniquement à naviguer.

Le mode le plus célèbre de Emacs, et qui dérive également de outline-mode, est org-mode, qui fut créé en 2003 ⁶, soit environ un an avant Markdown. Ses fonctionnalités sont beaucoup plus vaste, car s'ils permet un syntaxe de formatage, org-mode est avant tout un gestionnaire de tâche, voire de projet, ou même insérez ici quelque chose de farfelu. Donc tout markdown à son équivalent chez org-mode, l'inverse étant loin d'être vrai.

Un peu de comparaison de la syntaxe mardown / org mode.

1. Titre
   • MK : # niveau 1, ## niveau 2
   • ORG : * niveau 1, ** niveau 2
2. Gras
   • MK : **gras**
   • ORG : *gras*
3. Italique
   • MK : *italique*
   • ORG : */italique/*
4. Souligné
   • N'existe pas en MK
   • ORG : souligné
5. Barré
   • MK : ~~construisez des prisons pas des écoles!~~
   • ORG : +vive le privateur!+
6. Référence
   • MK : [^1] puis en bas [1]: ma note
   • ORG : [fn:1] puis plus bas [fn:1] ma note
7. Citation
   • MK : > Une ligne de citation commence par >
   • ORG : #+BEGIN_QUOTE un commentaire contructif #+END_QUOTE

8. Liste

   • MK :

     1. un
     2. deux
     3. trois
        + une liste non numérotée à l'intérieur d'une liste numérotée!
        + voilà on pourrait continuer longtmeps
   

• ORG : bah en gros c'est pareil

Les listes : les deux syntaxes permettent de rédiger une liste à l'intérieur d'une liste. Powa Bunga! En org-mode, pour marquer un élément de liste on commence une ligne par un chiffre ou - ou +, en Markdown c'est chiffre ou * ou - ou + (parce que en org le * est réservé aux titres). Toujours concernant les listes, sous Emacs, si vous êtes sur un élément, Alt+Entrée insérera un nouvel élément de liste. Voilà voilà!

Les Tableaux ne font pas partie de la spec à la base. Mais bon y'a du Markdown qui le gère. Un tableau s'écrit comme cela en Markdown

| bon voilà je mets la barre verticale | une deuxième sépare la colonne |
|--------------------------------------|--------------------------------------|
| ensuite l'espace se gère | enfin en tout cas dans Emacs! |
| on peut même appeler des commandes | pour insérer des lignes ou colonnes! |

Dans org-mode en gros c'est pareil.
Bon si vous cherchez bien vous trouverez
une micro différence!

| mon tablea | une deuxième colonne |
|------------+----------------------|
| voilà      | c'est la même!       |

Ce qui est sympa est que pour démarrer un tableau, dans markdown mode comme org-mode, on tape simplement | en début de ligne, puis on appuie sur <TAB>, et là bam! magie. Ensuite quand on créé des lignes et des commandes tout s'indente comme il faut.

Pour créer un paragraphe en markdown, on saute deux lignes. Un saut de ligne simple sera exporté comme un retour charriot - mais certaines implémentations de la conversion HTML ignoreront tout simplement le saut de ligne (genre pour les commentaires sur le web).

Conclusion, si le markdown-mode est correctement supporté par Emacs, la syntaxe org-mode, pour la partie texte riche, structuration basique, annotation , n'a donc pas à pâlir devant markdown. Attention par contre la syntaxe peut devenir beaucoup moins humaine lorsqu'il s'agit de fonctionnalités avancées de org-mode. La citation ne fait pas vraiment partie des fonctions habituelles de org-mode et peut illustrer cela. (Bon sans parler des raccourcis mais là ce n'est plus le sujet!!)

À quoi bon donc utiliser markdown mode sous Emacs? Bah simplement à travailler directement dans cette syntaxe comprise de tant d'autres applis que Emacs. Bien sûr vous pouvez rester en org mode puis utiliser les commandes pour convertir en markdown. Voire rediger un document mardown à l'intérieur d'un fichier org. Pourquoi faire simple? On parle de Emacs après tout…

Quel que soit le mode (org, markdown), vous pourrez exporter en HTML ou autre et il est possible que vous puissiez écrire et publier vos articles de blog directement depuis Emacs. (Je n'ai jamais utilisé mais bon.)

Petite note : à force de jouer avec la syntaxe je vois qu'on peut quand même créer des bugs dans le mode Markdown. La prévisualisation s'emmêle un peu ; ça m'aurait étonné! Vive les zéros et les uns. Puisque fermer le document et le réouvrir résout le problème; et qu'il faut de nombreux allers retours pour le provoquer, ça passe.


Vim

Il va de soi que vim supporte le markdown. Ouvrons le donc ah bah ça y est il est déjà ouvert. Deux petites parenthèses :
1. je n'ai pas testé Neovim mais à priori pas de changement à attendre là dessus
2. alternativement à vim, des éditeurs de texte dédiés markdown proposent les touches vim. À quel point c'est complet je vous laisse me dire dans les commentaires =)

J'ai testé un mode markdown de 2012, vim-markdown, qui fut écrit par Benjamin D. Williams ⁷. On peut installer son package de différentes manières, j'ai testé avec Vundle. Facile. Même une homme politique y arriverait. Edit: on me signale que non.

Le folding se gère avec les commandes vim habituelles. Le plugin ajoute des commandes de navigation, de structuration, de formatage des tableaux (:TableFormat, que je trouve tout de même un peu pénible à appeler alors que je suis habitué à l'avoir en auto ; je ne sais pas si les vim'ers keymappent beaucoup ou peu). On peut également se créer une table des matières pour naviguer. La touche o sur une liste va automatiquement insérer un nouvel élément de liste. Vous devrez vous appuyer sur un programme externe à vim pour générer l'export.

Bref tout semble là, mais comme je l'écrivais il n'y a pas qu'un seul plugin markdown. Voyez par exemple un courte discussion reddit ici ⁸ - reddit c'est tellement plein de bons conseils!

Éditeurs de texte : les jeunes

Chez les éditeurs modernes j'ai constaté une approche plus modulaire. À vous de vous constituer votre markdown, pièce par pièce.

Atom

Arf déjà je colle du markdown dans Atom pour voir, paf le chien, la moitié n'est pas bien rendue. Donc la première expérience refroidit presque autant que la pluie normande en février. (Je rigole, vive la crème fraîche.) Bon allez cela dit notons qu'il y a tout un tas de package destinés au markdown : pour améliorer le parsing / ajouter d'autres variantes, export en pdf, folding, insérer des images, tout plein de choses. Donc je suppose qu'en installant les bons on arrive à une bonne expérience. Ça vous fera un tas de paquet à tester par contre.

On retrouve un petit peu cet avis sur ossblog ⁹ (les grands esprits se rejoignent, hein).

Sublime

Rappel : Sublime est propriétaire. Bouh.

Bon Sublime ne fait rien d'emblée. Donc il faut lui installer un premier package pour le rendu syntaxique, puis un autre pour l'export html, un autre pour le folding, un autre pour aligner les tables. Voyez une description claire ici (^{http://putaindecode.io/fr/articles/sublime-text/markdown/).} Donc pareil que Atom on va être dans du modulaire.

Brackets

Euh désolé mon yaourt -Sy brackets prend des heures, c'est un peu comme La Poste. Encore un peu… ah je vide le cache de 25go de pacman, je relance.., arf non je dois augmenter le quota alloué à /tmp (qui par défaut 50% de RAM), reboot & relancer,… Nous y sommes! (pinaise j'aurai du passer par AppImage là!)

Brackets gère de base la coloration syntaxique, donc comme Atom, sauf qu'il semble un peu mieux la gérer. Dans le gestionnaire d'extension, on trouve deux extensions pour avoir des preview, une pour avoir une barre d'outil spécifique. Je n'arrive pas à installer les extensions mais, il semble bien que Brackets soit un peu léger là.

Encore d'autres éditeurs

Je pense qu'après les mastodontes (VIM Emacs Atom Sublime), nous aurons deux cas : soit un éditeur plus léger ne gérant que l'aspect coloration syntaxique, comme gedit - encore qu'avec des plugins gedit puisse faire un peu mieux-, soit un éditeur dédié Markdown ne gérant que cela. Ce n'est pas vraiment ce que je cherche sous Linux, mais ossblog ⁹ en liste plusieurs qui pourraient vous intéresser (Harroopad, Abricotine, StackEdit…). Harrropad gère les raccourcis vim.

Y'en a qui masquent carrément la syntaxe. Bon ça c'est pas mon truc. L'éditeur tu écris d'abord **cela, puis tu tape deux fois **, et là au lieu de laisser affiché ce que tu as tapé **cela** eh bien il n'affiche plus que cela. Une aberration quant à la philosophie originelle. Cependant si vous pensez le contraire eh bien, je vous présente md-editor ¹⁰.

L'export en HTML

Bon une fois qu'on a son fichbar en .md ou .markdown, vous voudrez parfois générer le HTML promis. Et la déjà qu'on sort d'une guerre d'éditeurs, on tombe dans le clash des worflow. À noter que je parle ici de fichier, mais on peut imaginer exporter seulement un bout, je pense par exemple dans Emacs a l'export de la sélection.

Comme on l'a vu en intro, le créateur de Mardown a codé un outil pour convertir le md en HTML : markdown.pl, un script perl, que vous pouvez donc utiliser, soit en l'invoquant vous même, soit parce que votre éditeur préféré l'appellera pour vous.

Ce script perl, n'est pas la seule solution. Il y en a écrit en C, Haskell… Ou on peut utiliser pandoc. Voici une petite page de comparaison ¹¹ : pandoc est différent, notamment car il gère plus de formats d'export, mais aussi parce qu'il ajoute des choses, comme les notes inline. Si je compare par exemple le script perl avec pandoc, sur ce document, il y à déjà le tableau que seul pandoc sait interpréter, ensuite pour les notes pandoc remplace le "nom" de mes notes par 1, 2, 3, 4, .. en mettant dans le bon ordre.

Alors attention, comme il y a plusieurs versions de mk il y a eu tentative de normer tout ça, le CommonMarkdown ¹², sans que ça n'ait encore aboutit - ils devaient d'ailleurs proposer un truc en 2017 doc ils sont en retard, tout est fichu on va tous mourir. Bref, donc les différents outils de conversion vont différer, et sur certains points ce sera délibérément.

Ensuite il y a le Github Flavoured Markdown (GFM) ¹, qui diffère encore… tient ce serait peut-être lui le prétendant au markdown universel? En fait le GFM est bien une suite au CommonMarkdown. Par rapport au Markdown original, GFM ajoute le barré, l'autolien : je tape juste https://linuxfr.com et le lien se fait automatiquement, les tableaux, les listes de tâches comme ça
- [ ] je dois vraiment finir cette dépêche
- [ ] mais j'ai la vaisselle à faire
- [x] mais d'abord je dois acheter le liquide vaisselle.

Nous sommes repartis pour un tour : dans Emacs on aura en complément du markdown mode le gfm-mode, dans vim le plugin vim-gfm-syntax, … ou pas : comme on parle surtout d'ajouts à la spécification, le même mode peut tout gérer sans problème. Vos retours d'expérience sur le sujet seront appréciés.

À propos de Android

ps oui bon je sais on chroot et sous android on vim ou emacs mais là c'est vraiment pas mon sujet du tout et pis voilà!

bon je ne vais pas me substituer au play store ou fdroid, il existe bien sûr de (trop?) nombreux éditeurs de markdown sur Android. Dont du libre. Citons d'abord Simple Markdown ¹³, qui propose d'avoir deux rendus, le rendu pur texte, de l'autre le rendu du résultat. A mon goût c'est un peu dommage de ne pas avoir la live preview mais il est vrai que ce type de fonction peut être une tannée à implémenter!

Ensuite il y a Markor ¹⁴, mais qui est fait pour prendre des notes.
Si on s'aurorise le propriétaire (déconseillé en pleine période de Ramadan) alors comme de coutume sur Android la liste devient gigantesque.

En guise de conclusion

Bon bah vive le markdown, espérons juse que GFM permettra d'avoir vraiment une syntaxe prenant le pas sur les autres, peut être-ce déjà le cas après tout.