Le tango des éditeurs markdown

Écrire en markdown présente de nombreux avantages, notamment en termes d’interopérabilité et de conversion de documents. Encore faut-il avoir à disposition un environnement de travail adéquat. De nombreux inventaires recensent des éditeurs en ligne fort agréables, mais qui ne se prêtent pas forcément à tous types de travaux. Voici une explication de mes choix.

Le contexte

Tout à commencé lorsque, pour les besoins éditoriaux de la collection Framabook, les limites d’une unique ligne éditoriale se sont fait sentir. En gros, il s’agissait de travailler les documents en LaTeX, quitte à les convertir depuis les sources de l’auteur, pour les publier en PDF puis assurer leurs transformations ultérieures en HTML et e-pub. Pour certains ouvrages, notamment des manuels très spécifiques, cette ligne éditoriale n’a pas changé, notamment parce que la publication en e-pub n’est pas forcément intéressante. Pour d’autres ouvrages notamment des romans et des essais, la question s’est posée en ces termes dans la communauté Framabook : « comment éviter de devoir scinder le processus de publication à la fin de la phase de relecture et devoir transformer des textes déjà formatés, avec tous les risques d’erreur que cela comporte ? »

La première partie de la solution était assez simple : trouver un format qui soit facile d’utilisation, compréhensible par tout le monde1, et surtout d’assez bas niveau pour pouvoir être transformé efficacement dans d’autres formats. Markdown présente l’avantage d’être simple et, bien que sa syntaxe officielle soit très basique, il existe la possibilité de laisser à des logiciels la possibilité d’adapter cette syntaxe au format de sortie voulu. C’est ainsi par exemple que Pandoc, un convertisseur très puissant, peut venir s’interposer entre la source et le format de sortie. Le texte de M. Dominici « Un aperçu de Pandoc » pourra vous donner une idée assez précise des capacités de Pandoc, en particulier lorsqu’on couple la conversion avec des modèles préalablement disposés.

Les choix

Or, donc, pour travailler de longs textes en markdown, la question n’est pas tant de trouver un bon éditeur markdown que de se concocter un environnement de travail adapté. C’est à dire qu’il faut pouvoir à la fois

  • éditer du texte avec un éditeur disposant à minima de la coloration syntaxique adaptée au markdown,
  • stocker ses fichiers et pouvoir les passer à la moulinette Pandoc avec un terminal,
  • être en mesure de transmettre ses fichiers en vue d’une édition collaborative,
  • et faire le tout avec des logiciels libres.

Il existe une pléthore de soit-disant « éditeurs markdown », certains sont des éditeurs de texte connus qui intègrent le format markdown dans leurs fonctionnalités, d’autres sont des éditeurs en ligne plus ou moins efficaces. Cet article sur Mashable recense pas moins de 78 éditeurs markdown. Beaucoup de ces éditeurs ne sont pas libres bien qu’étant parfois tout à fait efficaces et agréables. Tous n’offrent pas d’interface wysiwyg, c’est à dire la possibilité d’afficher « en live » la sortie HTML du document markdown. C’est le cas par exemple du très bel éditeur Sublime Text, malheureusement non libre.

Beaucoup de solutions sont en réalité des éditeurs en ligne. Beaucoup offrent des interfaces avec des solutions cloud, c’est à dire la possibilité d’éditer des documents stockés sur des espaces de type Dropbox. C’est le cas par exemple de Dillinger (sous licence as is), qui transforme votre navigateur en éditeur markdown soit pour enregistrer/éditer des fichiers locaux soit pour les stocker dans le cloud. Dans le même genre, Markdown Dingus est le convertisseur « officiel » de John Gruber, le créateur de markdown.

Ce type de solution est en réalité adapté à l’édition de documents courts, souvent destinés à être affichés sur le web. C’est pour les mêmes raisons pratiques, que des CMS comme WordPress proposent désormais le markdown pour éditer des articles. Une autre application de cela est illustrée par Strapdown.js qui permet d’insérer directement dans une page HTML des éléments en markdown, le tout affiché avec un style Bootstrap, très pratique pour éditer très rapidement des pages web élégantes.

Mais tout cela n’est guère adapté à l’édition…

Qu’est-ce qu’un bon éditeur markdown?

Comme je travaille sous GNU/Linux, je répondrai à cette question en adoptant une posture « Unixienne » : un bon logiciel est un logiciel qui fait juste ce que vous lui demandez et le fait bien. C’est-à-dire pas un moulin bourré d’options dont vous n’avez pas l’usage, ni un éditeur qui réinvente la pluie sous prétexte d’être moderne et qui marche moins bien que l’éditeur avec lequel vous travaillez depuis des années. Donc il n’y a pas de mauvais éditeur dans le sens où si vous y trouvez votre compte, tout va bien. Par contre je ne parlerai pas de ceux qui ne sont pas libres /open source, et je vais me concentrer sur mes usages personnels.

Gitbook : oui, mais non

[edit du 01 juin 2017 : les arguments ci-dessous laissent à penser que Gitbook n’est utilisable que sous Github, mais il s’agit de l’interface. Gitbook, le moteur, lui, est utilisable avec n’importe quel service basé sur Git (commeGitlab), mais on ne peut alors utiliser l’interface proposée par Gitbook, le service.]

Un bel exemple de bouzin, c’est le projet Gitbook (sous licence Apache). Mais je vais être gentil : il est beau, accueillant, et permet d’utiliser des dépôts Git (sur Github) sans se perdre dans les lignes de commandes. Son défaut ? se concentrer uniquement sur l’édition de livres (c’est normal, vu son nom) mais en voulant intégrer tout une ligne éditoriale d’un seul tenant, de l’édition du document markdown à sa publication en PDF voir en papier.

Dédié à la rédaction collaborative, Gitbook permet d’éditer un livre à plusieurs mains en travaillant au format markdown. L’interface web d’édition, dans la version gratuite, est fort bien conçue : outre l’aperçu direct de la sortie HTML, ses outils permettent d’exporter le document en HTML ou PDF, et il est possible d’uploader directement des fichiers (au format markdown, ou bien des images, etc.). Un fichier Summary.md permet de fabriquer le sommaire de l’ouvrage. Par ailleurs, il est possible d’interfacer directement Gitbook avec un compte Github, ce qui présente deux avantages :

  1. la synchronisation entre les fichiers avec le dépôt Github fonctionne dans les deux sens, si bien qu’il est possible de pousser ses fichiers rédigés localement pour mettre à jour le livre sous Gitbook, en inversement.
  2. Il n’est pas possible, sauf par copier/coller de récupérer le source markdown depuis Gitbook, donc pouvoir le faire depuis le dépôts Github se révèle plutôt pratique.

Le principal défaut de Gitbook, je l’ai dit, c’est de penser l’ensemble comme une solution éditoriale. Or ce n’est pas le cas. Premièrement parce que transformer du markdown vers du HTML puis vers du PDF, revient ni plus ni moins à vouloir imprimer une page web. Il est certes possible de configurer les styles de son ouvrage, mais la typographie ne sera jamais au rendez-vous. Sauf à se contenter de format HTML ou E-Pub, il n’est pas sérieux de prétendre remplacer un logiciel fait pour l’édition papier comme LaTeX. Mais ce n’est pas le plus important des griefs : il n’est pas possible de gérer une bibliographie digne de ce nom et toutes les subtilités éditoriales passent à la trappe comme par exemple la gestion des notes de bas de page, notes de fin, ou de fin de chapitre, les index, les tables des matières et les sommaires, les étiquettes, etc. Tout se passe comme si tous ces éléments devaient être construits « à la main », directement en HTML, ce qui est loin de faciliter la rédaction.

C’est la grenouille qui se prend pour le boeuf : les outils intégrés qui prétendent à la fois s’affranchir des formats et produire des sorties adaptées à tous les supports, n’existent pas.

Gitbook Editor

Gitbook Editor

Pourtant le projet Gitbook a produit un éditeur markdown très intéressant qui allie l’édition wysiwyg et la gestion des fichiers composant l’ouvrage. Cet éditeur en ligne existe aussi en version locale sous le nom Gitbook Editor. Très simple à l’installation (et toujours sous licence Apache), il permet de synchroniser vos fichiers comme expliqué précédemment sans toutefois dépendre d’une connexion Internet.

Néanmoins, s’il ne s’agit plus que d’utiliser un éditeur markdown et synchroniser des fichiers, hé bien, il suffit dans ce cas soit d’enregistrer directement ses fichiers dans un dossier synchronisé sur un compte cloud soit d’utiliser Git sur un compte Gitlab (ou Github). Dans les deux cas, il possible de rédiger de manière collaborative sans avoir besoin de disposer d’une interface web. Le principal avantage de Gitbook réside dans son apparente simplicité d’utilisation, mais au prix d’un résultat plutôt moyen.

En local, un éditeur markdown wysiwyg qui a largement fait ses preuves, c’est Re-Text. Sa simplicité d’utilisation est confondante et l’aperçu HTML est de très bonne qualité. Notons qu’il permet l’export en HTML, PDF mais aussi ODT, ce qui est assez appréciable d’autant plus que ces exports sont très propres.

Pourtant, ReText n’est pas encore à la hauteur de mes attentes.

Retext

Retext

Éditeurs de la Vieille école

Oui, je vous vois venir de loin : n’ayant pas trouvé mon bonheur dans les nouveautés, je cache mon inadaptation chronique de vieux schnock derrière la nostalgie du « c’était mieux avant »…

Détrompez-vous, ce n’est pas le cas. Je rappelle juste un point : n’importe quel éditeur peut faire l’affaire, pourvu que la coloration syntaxique puisse intégrer le markdown et qu’il soit possible de faire ce qu’on veut avec les fichiers sources.

L’important, c’est de trouver un éditeur le plus agréable possible et dont l’interface permette facilement ces manipulations. Voici donc, de manière affinée, le cahier des charges :

  • coloration syntaxique markdown,
  • aperçu HTML (en wysiwyg) non obligatoire mais appréciée,
  • un terminal intégré (pour compiler avec Pandoc et même LaTeX),
  • un navigateur de fichiers,
  • une interface agréable (si possible configurable à souhait).

Pour le reste, Pandoc nous permettra aussi de gérer toutes sortes de petits à-côtés, de la bibliographie à l’utilisation de modèles, et une foule d’options adaptées à l’édition. Cela implique forcément d’utiliser une saveur de markdown à la « sauce » Pandoc. D’où l’importance d’avoir un éditeur de texte dont la coloration syntaxique sera capable de comprendre plusieurs langages autres que le markdown, susceptible d’être intégrés directement dans le document source : le HTML, bien sûr, mais aussi du LaTeX, par exemple. Pour rappel, reportez-vous ici pour comprendre tout ce que Pandoc peut faire.

Gedit et Geany

Tout cela pour en arriver là… Gedit et Geany sont des éditeurs de texte figurant parmi les plus connus du Libre. À mon sens, c’est justement à cause de cela que leurs fonctionnalités ont été pensées au plus près des évolutions des usages, et l’édition de texte en markdown figure parmi celles-çi.

Au moins dans leurs versions récentes, ces deux éditeurs possèdent des fonctionnalités adaptées au markdown, à commencer par un panneau d’aperçu du rendu HTML. Leurs autres avantages est de permettre de naviguer dans l’arborescence, d’ouvrir plusieurs fichiers en même temps et d’avoir une interface de terminal intégrée, ne serait-ce que pour compiler.

Leurs différences ? Alors que Geany s’installe avec toute une batterie de fonctionnalités parfois assez sophistiquées, il faut installer ses greffons à Gedit. Là où Geany propose une interface assez complète permettant de configurer les préférences de l’éditeur, Gedit mise sur la simplicité. Dans les deux cas, pour ce qui concerne l’édition en markdown, la configuration reste la même à peu de choses près.

Dans les captures d’écran suivantes, j’ai simplement placé la barre d’aperçu HTML en bas (à coté du terminal intégré) dans Gedit, alors qu’elle figure dans le panneau de gauche sous Geany.

Avec ces deux logiciels (sous GTK) il est alors possible de travailler des documents en markdown de les convertir avec Pandoc, les compiler avec LaTeX, éditer des modèles LaTeX et HTML, éditer les sorties LaTeX et HTML si besoin, pousser les fichiers sur un dépôt Git, tout cela sans jamais sortir de l’interface. Et encore, même pour voir le rendu PDF, il est possible d’ajouter un panneau qui fera tourner un lecteur PDF comme Evince.

Il y a deux petites choses qui me font préférer Gedit pour l’écriture :

  • je trouve que la coloration syntaxique du markdown sous Gedit est plus évoluée que sous Geany, à moins d’avoir quelques minutes pour la configurer selon ses souhaits.
  • sous Gedit, j’ai trouvé un thème qui m’est vraiment agréable pour les yeux. il se nomme Build et il est disponible sur la liste des thème pour Gedit.

Ces deux éléments peuvent être retrouvés sans nul doute sous Geany, mais en passant un peu plus de temps dans la configuration.

Finalement, on est vraiment pas loin d’Emacs, sauf que je n’ai jamais résisté à plus de 5 minutes d’apprentissage… mais je suis persuadé que d’autres que moi y trouveront largement leur compte.

D’autres éditeurs de texte pourront de même être testés, il suffit pour en obtenir une liste assez exhaustive de se pencher sur la comparaison sur cette page Wikipédia.

Gedit

Gedit

Geany

Geany

Conclusion

Autant il est facile d’apprendre la syntaxe markdown, autant il est important de bien choisir les outils qui permettront de traiter les fichiers sous ce format, en fonction du but recherché. S’il ne s’agit que d’écrire un billet de blog, n’importe quel éditeur de texte pourvu de la coloration syntaxique (et encore) fera l’affaire. Choisissez-le sous licence libre si possible car tout ce que proposent de plus les éditeurs non libres sont des interfaces (parfois) très agréables, mais c’est tout.

Pour l’édition de documents longs, avec des exigences de mise en page, de typographie et d’utilisation de données (comme de la bibliographie), le markdown est d’abord à concevoir comme un outil de saisie rapide et propre à être converti en plusieurs formats. Dans ce cas, il est important d’utiliser des éditeurs de textes qui proposent des outils de traitement des opérations nécessaires à la conversion. L’expérience apprend qu’il est presque toujours nécessaire de retoucher les fichiers ainsi convertis en vue d’une publication, et ces retouches doivent être faisables avec le même éditeur, de manière à ne pas avoir à changer d’interface pour chaque opération.

Quitte à rester simple dans le format de départ (markdown), autant rester simple dans le choix de l’éditeur. L’utilisation de la ligne de commande n’est pas une obligation, mais c’est quand même très pratique.

Pour ce qui concerne l’édition collaborative, la solution de synchroniser sur un dépôt Git me semble la plus recommandée. On pourra éventuellement utiliser Gitbook mais il ne fonctionne que sous Github (dont on sait la politique pas franchement libre). Avoir un dépôt cloud basé par exemple sur Owncloud, peut aussi être une bonne alternative. Il suffit alors de synchroniser le dossier dans lequel on travaille. On peut aussi signaler que Owncloud dispose en ligne d’un plugin qui permet d’éditer des fichiers markdown, cependant peu adapté à de gros documents.


  1. Certains pensent toujours que LaTeX est réservé à une élite, ce qui est vrai, mais tout le monde peut en faire partie !
 

Christophe

Fram(hack)tiviste, je fais du vélo et je mange des châtaignes.