Les outils en ligne

On peut trouver nombre d’outils en ligne pour éditer au format Markdown. Les transformations sont variables d’un site à l’autre, du CommonMark^[1] à une gamme très complète de commandes interprétées et de formats produits.

Ces sites Web permettent non seulement de se familiariser avec Markdown mais sont aussi des outils d’écriture collaborative en substitution d’outils (GAFAM) comme Google Docs.

Les outils les plus courants sont :

• HedgeDoc^[2]
• markup.rock^[3]
• Dillinger^[4]
• Stack Edit^[5]
• Preview Markdown^[6]
• Markdit^[7]
• HackMD^[8]
• Stylo^[9]

On les utilise via le navigateur, sans installation. Les deux derniers nécessitent une inscription, gratuite. Avec HackMD, on peut produire une page web qui peut être partagée. Stylo^[10] pousse très loin tous les aspects de l’écriture académique (voir l’aide^[11], très complète).

Du côté des outils en ligne, il y a aussi les outils spécifiquement développés pour la prise de note collaborative comme Framapad^[12], Etherpad^[13] ou le Pad “domaine public”^[14], basé sur le même logiciel.

Pour travailler en mode local avec toutes les fonctionnalités liées au Pandoc-Markdown, il faut nécessairement installer Pandoc et LaTeX.

Les outils pour éditer

Un simple éditeur de texte (comme Notepad pour Windows, Simplenote pour un Mac ou Xed pour Linux) peut être utilisé pour créer et gérer les fichiers Markdown. Des éditeurs comme Atom^[15] ou Komodo Edit^[16], particulièrement appréciés par les programmeurs, intègrent aussi le format Markdown^[17].

Pour débuter, il y a également Typora^[18] qui permet de se familiariser avec Markdown. Il guide l’utilisateur dans l’installation de Pandoc et de LaTeX. MarkText^[19] est une alternative libre à Typora. Il propose moins de fonctions (en exportation par exemple).

Zettlr^[20] est un autre logiciel libre qui commence à avoir beaucoup de succès. Il propose une aide très complète mais il est un peu moins aisé à prendre en main.

Il y a également Ghoswriter^[21] qui intègre plusieurs modes d’édition, de visualisation et d’exportation.

Cette courte liste n’est pas exhaustive, il existe bien d’autres logiciels qui permettent d’éditer des textes Markdown. Ces logiciels sont soit spécifiques à un système d’exploitation (Windows, Mac ou Linux) soit utilisables sur les trois. Une recherche rapide sur un moteur de recherche^[22] va permettre de découvrir des listes des logiciels les plus récents et/ou les plus appréciés.

Ces logiciels poussent parfois très loin le principe de l’écriture sans distraction avec des écrans sans menus, uniquement le texte en cours de rédaction.

Typora et Marktext vont automatiquement intégrer les balises Markdown dans l’affichage. Il est toutefois possible, par une simple combinaison de touches de les faire apparaître. Ghoswriter va par contre permettre la prévisualisation avec à gauche le texte brut, balisé, et à droite le rendu après interprétation. La majorité des outils qui proposent la prévisualisation (soit via un éditeur soit en ligne), vont proposer une transformation html avec la syntaxe Commonmark. Avec Ghoswriter, il est possible de choisir de manière plus fine le mode de prévisualisation (Pandoc-Markdown par exemple).

Malgré la “simplicité” de Markdown, il faut consacrer un certain temps à le maîtriser surtout si on est habitué aux traitements de texte tels que Word voire LibreOffice. Les éditeurs Markdown permettent de reproduire en partie ce que les traitements de texte proposent au moyen d’extensions (vérifier la grammaire, l’orthographe, l’affichage de l’historique des modifications ou le code).

Une tâche apparemment simple comme l’insertion d’une image ou d’un tableau peut être parfois difficile avec Markdown. Tous ces logiciels sont différents. Il ne faut donc pas hésiter à passer du temps à les essayer avant d’en adopter un (ou plusieurs en fonction de leurs spécificités).

Les outils de transformation

Pandoc

Pandoc a été créé en 2006, et est toujours maintenu, par John MacFarlan^[23]. C’est un logiciel libre (publié sous licence GPL) considéré comme le couteau-suisse de l’édition. Il permet de passer facilement d’un format de fichier à un autre.

Pandoc gère plus de 50 formats différents^[24] !

 

Pour installer Pandoc il faut se rendre sur la page (https://pandoc.org/installing.html) et télécharger le fichier qui correspond au système d’exploitation que l’on utilise.

LaTeX

LaTeX est un système de composition de documents, idéal pour les textes scientifiques et techniques. Il permet une séparation claire entre le contenu et la mise en forme, offrant un contrôle précis sur la typographie et les équations mathématiques.

LaTeX est une extension de TeX, un langage de programmation de mise en page développé en 1977. LaTeX, existe depuis 1982 et n’a pas cessé d’être amélioré. Il est actuellement maintenu par une équipe de bénévoles au sein du projet LaTeX3, assurant sa pérennité et son évolution.

LaTeX produit des documents au rendu professionnel, avec une mise en page soignée. Il excelle dans la composition de formules mathématiques complexes, la création de bibliographies, tables des matières et de renvois. Avec LaTeX, Les utilisateurs se concentrent sur le contenu, tandis que LaTeX gère la mise en forme automatiquement. LaTeX est extensible avec de nombreux packages (voir dans la troisième partie) pour répondre à des besoins spécifiques.

Pour installer LaTeX, le logiciel à installer dépend du système d’exploitation :

• pour Linux, on va préférer Texlive. Pour l’installer, dans un terminal, on va entrer la commande :

sudo apt-get install texlive texlive-xetex texlive-latex-extra texlive-lang-french

• pour MacOS, on va utiliser MacTeX qui est téléchargeable à l’adresse : https://tug.org/mactex/mactex-download.html. Ce programme s’installe comme tous les autres programmes sur un Mac (double clic sur un fichier avec extension “.dmg”) ;
• pour Windows, on va préférer MiKTeX. Le lien de téléchargement est : https://miktex.org/download.

Avec MiKTeX (qui peut aussi être installé sur Linux ou MacOS), il faut bien lire les instructions sur la page de téléchargement. L’installation doit être complétée via “MiKTeX Console” (que l’on va appeler via le menu “Démarrer” de Windows, à gauche).

Il faut passer en mode administrateur MiKTeX. À partir de là accéder à la page des mises à jour.

Il faut alors demander à MikTex d’installer automatiquement les paquets manquants et via la page “Settings” (paramètres), cliquer sur le bouton radio : Always install missing packages on-the-fly (pour éviter qu’il demande de confirmer l’installation des paquets manquants, un à la fois).

 

Pour vérifier l’installation de Pandoc et de LaTeX,  il faut exécuter, dans le terminal (voir ci-dessous) :

pandoc -v

et

latex -v

Si l’installation n’est pas conforme, la commande renverra une erreur.

La transformation

Par défaut, Pandoc s’utilise en mode terminal (ou ligne de commande).

Pour accéder au mode terminal, sur une machine Linux ou Mac, il faut chercher “terminal”. Pour Windows il faut entrer “cmd” dans la zone de recherche en bas, à gauche. Le terminal apparaît en général (à moins d’en avoir modifié les paramètres) sous la forme d’un petit rectangle noir avec le texte en blanc.

Le mode terminal permet d’entrer directement des commandes au système sans passer par une interface graphique. Pour l’utilisation de Pandoc, le nombre de commandes à retenir est réduit.

Il n’est pas nécessaire de maîtriser le mode terminal pour effectuer cette manipulation et les commandes listées ci-dessous sont sans danger pour l’ordinateur.

Pour que la commande fonctionne, il faut néanmoins préciser l’endroit où se trouve(nt) le(s) fichier(s) .md dans l’arborescence (“dir” sous Windows et “ls -l” sous Linux ou MacOS) ou se placer dans le bon répertoire (avec la commande “cd” pour change directory).

La commande Pandoc base est la suivante :

Le “-o”^[25] (pour output) doit précéder le nom du fichier destination. La destination peut aussi être un fichier .html, un fichier .epub voire .docx ou .odt (pour rappel Pandoc gère plus de 50 formats).

Il est possible d’utiliser plusieurs fichiers “sources” (parties, chapitres…) simultanément dans la commande. Ici, l’en-tête YAML se trouve dans le premier fichier, elle ne doit pas être répétée.

Si les fichiers sont numérotés (pour qu’ils soient traités dans le bon ordre, 01yalm.md 02intro.md, 03chap1.md, 04chap2.md…), on peut simplifier la commande :

Par défaut, Pandoc utilise pdflatex pour la transformation en pdf. Si le document contient des caractères spéciaux ou des polices spécifiques (message d’erreur lors de la transformation : Error producing PDF), on peut utiliser xelatex ou lualatex via l’option –pdf-engine. Dans la commande Pandoc :

Pour rappel, pour insérer une bibliographie, il faut ajouter –citeproc dans la commande de transformation :

Avec Typora, MarkText et plusieurs autres outils, il est possible d’exporter directement un fichier Markdown en fichier pdf sans quitter l’interface graphique.

Avec Typora le fichier créé n’aura pas une forme comparable à un fichier pdf produit via LaTeX (mise en page stricte et professionnelle avec utilisation des données YAML, numérotation des pages, notes de bas de page, équations mathématiques, citations et bibliographie…). Typora n’utilise que TeX Math de LaTeX.

Zettlr ou Ghostwriter vont eux utiliser directement Pandoc et LaTeX pour produire les documents pdf. Zettlr propose d’ailleurs des réglages très fins via la “gestion des assets” (commande Alt+Ctrl+,). Avec Ghostwriter les principaux réglages sont réalisés via l’en-tête YAML.

Les modèles

Il est possible d’utiliser des modèles (des templates)^[26] pour l’exportation.

Dans la dernière partie du manuel se trouve une liste de liens vers des templates LaTeX qui remplacent le template par défaut. Pour l’appeler, il faut ajouter le nom du modèle dans la ligne de commande.

Cette possibilité existe aussi pour les exportations .docx ou .odt. Après avoir créé un modèle (mise en page, styles, en-tête et pieds de page…) avec le traitement de texte, on fait appel à ce modèle dans la commande Pandoc.