Par­tie car­rée avec Pan­doc, Mark­down, HTML et LaTeX

(màj. 28/03/2018) Pour ceux qui en dou­te­raient encore, les blagues gra­ve­leuses à pro­pos de LaTeX n’ont pas cours ici. Il s’agit dans ce billet de pro­po­ser une mini chaîne édi­to­riale qui vous per­met­tra de com­po­ser rapi­de­ment des docu­ments en plu­sieurs for­mats tout en les écri­vant avec le mini­mum de contraintes. Qu’il s’agisse de n’importe quel logi­ciel de trai­te­ment de texte ou d’un simple édi­teur dans lequel on for­mate direc­te­ment le docu­ment source, on passe bien trop de temps à cli­quer ou entrer des com­mandes, tou­jours au détri­ment du conte­nu. Avoir une solu­tion auto­ma­ti­sée ne résou­dra jamais toutes les situa­tions, mais notre objec­tif est de tâcher de sépa­rer le plus pos­sible l’entrée de conte­nu et la mise en page. Pour cela nous allons uti­li­ser deux outils, à savoir le for­ma­tage Mark­down et le logi­ciel de conver­sion Pan­doc.

Pré­re­quis

Pour accom­plir toutes les opé­ra­tions men­tion­nées ci-des­sous, quelques condi­tions doivent être réunies :

  • Pour la plus grande par­tie de ce billet, il faut avoir com­pris (juste « com­pris ») ce qu’est un lan­gage de bali­sage comme le HTML ou le LaTeX, et savoir se ser­vir d’un ter­mi­nal (entrer des lignes de com­mandes, au demeu­rant fort simples à com­prendre) ;
  • Avoir Pan­doc ins­tal­lé sur sa machine ;
  • Avoir un bon édi­teur de texte, si pos­sible capable d’afficher une colo­ra­tion syn­taxique propre au Mark­down (voir cap­ture d’écran) ;
  • Pour obte­nir un docu­ment LaTeX et pro­duire un PDF, il faut avoir une dis­tri­bu­tion LaTeX ins­tal­lée, comme TeX­live.

screen_editeurmd

Objec­tifs

À quel genre de situa­tion sommes-nous cen­sés faire face ?

Vous sou­hai­tez rédi­ger rapi­de­ment un docu­ment, cepen­dant, avec votre logi­ciel de trai­te­ment de texte, vous sup­por­tez de moins en moins d’avoir à cli­quer sans cesse pour for­ma­ter des styles de titres et de para­graphes et vous aime­riez pou­voir rédi­ger avec une inter­face d’éditeur de texte la moins char­gée pos­sible.

Il vous est peut-être arri­vé de rédi­ger un docu­ment en LaTeX et, mal­gré les filtres dis­po­nibles, avoir toutes les peines du monde à le trans­for­mer en HTML parce qu’en fin de compte vous sou­hai­tiez l’afficher en tant que page web ou réa­li­ser un e-pub.

Vous avez essayé plu­sieurs sys­tèmes de conver­sion auto­ma­ti­sés, mais jamais vous n’avez fini par obte­nir de docu­ment pro­pre­ment for­ma­té.

D’autres situa­tions ont pu se pro­duire et vous allez cer­tai­ne­ment trou­ver des failles à la méthode pro­po­sée ici. En revanche, en plus de la méthode, je pro­pose un prin­cipe auquel on pense pas tou­jours : si vous vou­lez trans­for­mer un docu­ment, rédi­gez-le d’abord au for­mat le plus simple. C’est depuis cette source qu’il faut ten­ter les conver­sions et évi­ter de le faire depuis un for­mat com­plexe. Quoi que vous fas­siez, pour être par­fait, votre docu­ment final devra sans doute faire l’objet de retouches, mais elles seront un moindre mal car la majeure par­tie du docu­ment sera alors trai­tée pro­pre­ment.

Qu’est-ce que j’entends par « pro­pre­ment » ? C’est vrai­ment un conseil d’hygiène : cer­taines solu­tions de for­ma­tage ou de conver­sion uti­lisent des solu­tions plus ou moins adap­tées à la com­plexi­té du code de départ. Cela se tra­duit sou­vent par l’adjonction de styles pré­dé­fi­nis par le logi­ciel de conver­sion. Ain­si, si vous trans­for­mez un docu­ment LaTeX en HTML, la mal­léa­bi­li­té du docu­ment final lais­se­ra tou­jours à dési­rer, en par­ti­cu­lier si vous vou­lez adap­ter votre propre feuille de style, à moins de la défi­nir aupa­ra­vant ce qui néces­site en retour beau­coup d’efforts. Faire les choses sim­ple­ment dès le départ vous per­met­tra de com­plexi­fier par la suite à votre propre ini­tia­tive, mais en aucun cas vous ne serez contraints d’adapter votre pro­jet au for­mat : c’est l’inverse qui doit se pro­duire.

Les objec­tifs seront suc­ces­si­ve­ment :

  1. de pro­duire un docu­ment au for­mat Mark­down adap­té à Pan­doc,
  2. le trans­for­mer en uti­li­sant Pan­doc, de manière à pro­duire un docu­ment au for­mat .odt (ou .docx), un docu­ment au for­mat HTML,
  3. et un docu­ment .pdf (re)formaté LaTeX et com­pi­lé avec pdf­TeX ou Xe(La)TeX.

Créer un docu­ment au for­mat Mark­down

Le for­mat Mark­down est tel­le­ment simple qu’il n’y a pas besoin de créer des macros pour pou­voir l’utiliser. En d’autres termes, tout ce dont vous avez besoin pour écrire dans ce for­mat est d’un édi­teur de texte et d’un peu de mémoire. Si, en plus, vous uti­li­sez votre édi­teur en plein écran, sans autre affi­chage que votre cur­seur pour entrer des carac­tères, vous pour­rez vous concen­trer plei­ne­ment sur votre conte­nu et écrire sans vous sou­cier d’autre chose.

L’entrée des élé­ments de for­ma­tage en Mark­down s’effectue au long de la frappe. Ain­si, pour un titre de niveau 1, vous n’avez qu’à entrer un croi­sillon (# Titre 1) en début de ligne ; pour un titre de niveau 2, deux croi­sillons feront l’affaire (## Titre 2) ; pour mettre en valeur une par­tie de votre texte, par exemple en ita­lique, il suf­fit d’entrer le carac­tère tiret bas (_italique_) ou une asté­risque (*italique*) au début et à la fin de la par­tie ; etc.

Pour recon­naître votre docu­ment en mark­down, vous pou­vez lui ajou­ter l’extension .markdown, ou .md, par exemple.

Par ailleurs, il existe cer­tains édi­teurs de texte qui vous pro­posent d’afficher direc­te­ment le ren­du HTML de votre docu­ment. Ils uti­lisent par­fois une double fenêtre. Voi­ci trois édi­teurs sym­pa­thiques : Ghost­wri­ter, ReText, Sta­ckE­dit (fonc­tionne dans votre navi­ga­teur). Ces édi­teurs pro­posent aus­si des filtres d’export vers odt, HTML et PDF.

La liste des com­mandes de for­ma­tage Mark­down est très courte. Vous trou­ve­rez sur le site de son créa­teur, John Gru­ber, les élé­ments de syn­taxe uti­li­sables dans ce for­mat. En revanche, comme nous allons le voir, Pan­doc pro­pose quelques fonc­tion­na­li­tés spé­ci­fiques, aus­si il sera pré­fé­rable de se réfé­rer à cette par­tie du manuel de Pan­doc. En réa­li­té, il suf­fit de quelques minutes de pra­tique pour en maî­tri­ser l’essentiel. La seule dif­fi­cul­té du Mark­down, c’est qu’il n’est pas (encore) stan­dar­di­sé, si bien que tout le monde s’accorde à recon­naître l’essentiel mais de petites varia­tions peuvent appa­raître ici et là.

Dans notre cas, il y a une manière d’utiliser le Mark­down à la « sauce » Pan­doc. En voi­ci quelques exemples :

Les notes de bas de page

Le Mark­down est si simple que des élé­ments pour­tant essen­tiels à la rédac­tion en sont absents. C’est le cas de la ges­tion des notes de bas de page. Pan­doc per­met de gérer cela de manière très simple : il suf­fit d’entrer le numé­ro de la note à l’endroit de l’appel de note, puis, en fin de texte, rédi­ger la note en y fai­sant réfé­rence.

Ceci est un appel de note[^1].

(en fin de texte)

[^1]: Ceci est le contenu de la note de bas de page.

La ques­tion des notes de bas de page est loin d’être tri­viale. Si vous devez conver­tir votre docu­ment à la fois en HTML et en LaTeX vous consta­te­rez bien vite que les méthodes dont ces deux lan­gages bali­sés gèrent les notes de bas de page n’ont qua­si­ment rien à voir entre elles, si bien que conver­tir de l’un à l’autre un docu­ment conte­nant des notes de bas de page est sou­vent un vrai casse-tête, tout par­ti­cu­liè­re­ment si vous avez beau­coup de notes.

Les méta­don­nées

Les infor­ma­tions du docu­ment comme le titre, la date et l’auteur, pour­ront être entrées en début de docu­ment en les intro­dui­sant sim­ple­ment avec le signe %.

% Titre
% Auteur
% Date

Là encore, c’est une fonc­tion­na­li­té qui est pro­po­sée : vous ver­rez que, lorsque nous uti­li­se­ront un modèle de conver­sion, nous pour­rons uti­li­ser ces don­nées ren­dues exploi­tables par Pan­doc.

La table des matières

Pour créer une table des matières… hé bien, non, il n’y a rien à faire ! Il suf­fi­ra, lors de la conver­sion, de deman­der gen­ti­ment à Pan­doc de se char­ger de créer une table des matières selon le for­mat de sor­tie dési­ré.

Autres aspects du Pandoc’s Mark­down

Vous trou­ve­rez dans le manuel toutes les pos­si­bi­li­tés d’interprétation du Mark­down par Pan­doc, par exemple pour faire des tableaux, insé­rer des mathé­ma­tiques, faire des listes spé­ciales, etc. Sachez tou­te­fois que si vous vou­lez que votre docu­ment reste inter­pré­table par d’autres conver­tis­seurs que Pan­doc, il fau­dra aus­si faire un effort de sim­pli­fi­ca­tion. L’autre solu­tion est que, quoiqu’il arrive, selon le for­mat de conver­sion visé, vous pou­vez insé­rer direc­te­ment des élé­ments de code dans votre docu­ment Mark­down. Ain­si, si vous vou­lez trans­for­mer vers LaTeX, vous pou­vez insé­rer direc­te­ment du code LaTeX qui sera inter­pré­té tout à fait nor­ma­le­ment. Idem pour le HTML. Et même mieux : vous pou­vez insé­rer du code HTML dans du Mark­down et inter­pré­ter le tout vers LaTeX !

À pro­pos de Pan­doc

Dans la suite de ce billet, je vais vous mon­trer com­ment uti­li­ser cer­taines com­mandes de Pan­doc. Mais les pos­si­bi­li­tés de ce der­nier sont très vastes. Il est pos­sible, par exemple, de lui faire trai­ter de la biblio­gra­phie en tra­vaillant avec LaTeX et BibLa­TeX, ou encore rédi­ger un script qui per­met­tra d’automatiser cer­taines tâches avec Pan­doc. Fai­sons simple pour com­men­cer : Pan­doc pro­pose des options, uti­li­sons-les.

Par ailleurs, Pan­doc per­met de trans­for­mer de mul­tiples for­mats. Nous nous foca­li­se­rons ici sur le Mark­down, mais sachez que les appli­ca­tions de Pan­doc excèdent lar­ge­ment ce cadre.

Com­ment uti­li­ser Pan­doc ?

Pan­doc s’utilise en ligne de com­mande. Non, atten­dez ! ne par­tez pas tout de suite. D’accord, il s’agit d’ouvrir un ter­mi­nal mais il ne s’agit pas non plus d’incanter des for­mules réser­vées à un caste de moines guer­riers ini­tiés. Il faut pas­ser outre vos appré­hen­sions et vous allez voir, c’est vrai­ment simple.

Pre­mière chose à faire : ouvrir un ter­mi­nal et vous rendre dans le dos­sier où vous avez sto­cké votre docu­ment en Mark­down. Dans les com­mandes que je cite­rai plus bas, tout se pas­se­ra dans ce dos­sier : la pro­duc­tion de sor­tie sera enre­gis­tré à cet empla­ce­ment (mais vous pou­vez tou­jours en choi­sir un autre, il suf­fit pour cela de spé­ci­fier à chaque fois le che­min).

Les com­mandes se rédigent tou­jours de manière logique. On « dit à la machine », quelque chose comme « Tu vas uti­li­ser Pan­doc sur ce docu­ment au for­mat Bidule pour pro­duire ce nou­veau docu­ment au for­mat Machin, en uti­li­sant telle et telle option ». Les options sont tou­jours intro­duites avec un double tiret (--) ou leur dimi­nu­tif par un tiret simple (-).

Voi­ci un exemple simple que je com­mente :

pandoc mondocument.md -o masortie.html

Pan­doc est lan­cé, il trai­te­ra un docu­ment au for­mat mark­down pour pro­duire (-o, ou bien -output) un autre docu­ment au for­mat HTML. À chaque fois j’aurais pu pré­ci­ser un che­min dif­fé­rent pour chaque docu­ment, ain­si pour trai­ter un docu­ment d’un dos­sier à l’autre, on peut écrire :

pandoc chemin/redaction/mondocument.md -o chemin/production/masortie.html

Cerise sur le gâteau, si vous avez plu­sieurs docu­ment mark­down que vous dési­rez conver­tir pour pro­duire un docu­ment unique dans un autre for­mat, il suf­fit de les entrer dans l’ordre :

pandoc doc1.md doc2.md doc3.md -o docfinal.odt

Ceci est d’autant plus pra­tique si vous rédi­gez un livre, par exemple, avec un fichier par cha­pitre.

Pas­sons à la pra­tique

Vous avez donc rédi­gé un docu­ment au for­mat Mark­down. Qu’allez-vous en faire ?

Tel quel

Vous pou­vez tout sim­ple­ment uti­li­ser votre docu­ment tel quel. Le mark­down, c’est d’abord du texte. Par ailleurs, ce for­mat a été conçu spé­ci­fi­que­ment au départ pour envoyer des cour­riels en mode texte sans avoir à perdre du temps dans une mise en page dont le résul­tat est dif­fé­rent selon le para­mé­trage du client de cour­riel du des­ti­na­taire.

De plus, vos docu­ments en Mark­down seront lisibles par tout édi­teur de texte dans l’avenir. Vous pou­vez être cer­tain de leur péren­ni­té. Si vous ouvrez vos docu­ments Mark­down avec un édi­teur per­met­tant le ren­du HTML, vous avez en plus de cela une mise en page toute prête si l’aspect « texte » ne vous convient pas.

Vers un logi­ciel de trai­te­ment de texte

Si vous avez besoin d’éditer votre docu­ment avec un logi­ciel de trai­te­ment de texte comme LibreOf­fice Wri­ter ou MSWord, en par­ti­cu­lier si vous avez des modèles de mise en page à y appli­quer, la syn­taxe de la trans­for­ma­tion est la plus simple :

pandoc source.md -o produitfinal.odt

ou bien

pandoc source.md -o produitfinal.doc

Le docu­ment pro­duit sera mis en page avec les styles par défaut de votre logi­ciel de trai­te­ment de texte, il suf­fit ensuite d’y appli­quer vos propres styles si besoin.

Vers le HTML

S’agissant d’un lan­gage bali­sé, la conver­sion vers le HTML per­met d’intégrer des exi­gences de mise en page direc­te­ment au moment de le trai­ter avec Pan­doc. Ain­si, vous pou­vez pré­pa­rer une feuille de style .css en vue de l’intégrer (ou pas) direc­te­ment dans le docu­ment de sor­tie, ce der­nier pou­vant de même obéir à un modèle (tem­plate) pré­pa­ré à l’avance.

pandoc -s -S --toc --template=modele.html -H monstyle.css --number-section source.md -o produitfinal.html

Cette ligne de com­mande per­met de faire ces opé­ra­tions (vous pou­vez ôter celles qui nous inté­ressent pas) :

  • Pro­duire un docu­ment « stan­da­lone » (-s ou --standalone), c’est-à-dire qu’il inté­gre­ra toutes les infor­ma­tions pour qu’il s’affiche dans le navi­ga­teur sans faire appel à d’autres fichiers.
  • Le docu­ment aura une typo­gra­phie accep­table, grâce à l’option -S (ou --smart). Pan­doc conver­ti­ra par exemple les doubles tirets (--) par des demi-cadra­tins ou les triples tirets (---) par des cadra­tins
  • Il inté­gre­ra une table des matières au début, grâce à l’option --toc (ou --table-of-contents), notez que la pro­fon­deur de la TOC peut se régler avec l’option --toc-depth=nombre.
  • l’option --number-section per­met de numé­ro­ter les sec­tions, sous-sec­tions, etc.
  • Le tem­plate est défi­ni à l’avance, on le ren­seigne dans la ligne de com­mande avec --template=fichier.
  • Dans son en-tête (hea­der, -H ou en ver­sion longue --include-in-header=fichier), il inté­gre­ra la feuille de style que vous avez créée à cet effet, et que l’on ren­seigne en don­nant le nom du fichier (mais on pour­rait aus­si bien inté­grer le ren­voi à la feuille de style dans le tem­plate lui-même ; ici vous avez la pos­si­bi­li­té de choi­sir par­mi plu­sieurs feuilles de style si besoin).

Le docu­ment final affi­che­ra, en plus du titre, de la date et de l’auteur, une table des matières et toutes les infor­ma­tions de mise en page que vous avez inté­grées à votre docu­ment Mark­down.

Vous note­rez la ges­tion des notes de bas de page, par exemple, et la manière dont la table des matières s’affiche. Si vous aviez dû entrer toutes les réfé­rences internes de la page, cela vous aurait cer­tai­ne­ment pris beau­coup plus de temps.

Vers LaTeX (pdf)

C’est vers ce for­mat qu’on s’amuse le plus, à mon humble avis. Toutes les options sont appli­cables mais nous pou­vons aller beau­coup plus loin. En effet, nous cher­chons à auto­ma­ti­ser la créa­tion du for­mat de sor­tie le plus cou­rant de LaTeX, à savoir un beau docu­ment PDF. Tout l’intérêt de la démarche consiste donc à créer un style comme nous l’avons fait pour le ren­du HTML, mais beau­coup plus fin puisque nous pour­rons para­mé­trer une mise en page des­ti­née à l’impression. Il s’agira d’un docu­ment LaTeX conte­nant quelques élé­ments condi­tion­nels, les packages que vous sou­hai­tez uti­li­ser et la confi­gu­ra­tion de ceux-ci. En somme, c’est de toute l’en-tête du docu­ment que nous avons besoin. Si bien qu’une fois celle-ci défi­nie, il vous res­te­ra à l’avenir à rédi­ger vos docu­ments en Mark­down sans pas­ser par LaTeX (ou alors pour quelques retouches si besoin), tout en uti­li­sant les options de Pan­doc. Ce qui pro­duit fina­le­ment un double outil très puis­sant.

Dans l’exemple don­né, il s’agit de créer un docu­ment au for­mat A4, pré­sen­té comme un rap­port avec un en-tête, etc. Mais ce n’est qu’un exemple : à vous de modi­fier le modèle pour le confor­mer à vos besoins.

Par défaut, c’est-à-dire si vous ne spé­ci­fiez aucun style, la sor­tie PDF se fera sous la simple classe [article] sans style par­ti­cu­lier. Et n’oubliez pas : nous cher­chons à pro­duire direc­te­ment un PDF en uti­li­sant le moteur LaTeX, rien ne vous empêche de trans­for­mer votre docu­ment en LaTeX pour le tra­vailler ensuite.

Pour notre exemple, la syn­taxe est la sui­vante :

pandoc source.md -o produitfinal.pdf --toc --template=monstyle.latex --number-section
  • l’option --toc per­met l’insertion d’une table des matières
  • l’option --number-section per­met de numé­ro­ter les sec­tions, sous-sec­tions, etc.
  • l’option --template=xxx per­met de spé­ci­fier le style, c’est-à-dire l’en-tête du docu­ment LaTeX qui sera com­pi­lé pour pro­duire le pdf final, cet en-tête se rédige dans un docu­ment LaTeX auquel on fait appel lors de la com­pi­la­tion.

Mais enfin, com­ment se construisent ces tem­plates pour Pan­doc ?

Il s’agit en réa­li­té de modèles de com­po­si­tion qui intègrent toute une série de variables. Par exemple, pour la date à inté­grer dans un docu­ment LaTeX, on peut uti­li­ser $if(date)$\date{$date$}$endif, c’est à dire « si la date est ren­sei­gnée (dans les méta­don­nées), alors tu uti­lises cette valeur dans la com­mande indi­quée ».

On peut construire ses propres modèles, dans la mesure où les valeurs peuvent être uti­li­sées de cette manière. Mieux encore, cer­taines don­nées peuvent aus­si être entrées dans un fichier en YAML, mais cela fera l’un des objets d’un futur billet.

Pour com­men­cer à bâtir des modèles, vous pou­vez vous repor­ter à cette par­tie de la docu­men­ta­tion et sur­tout regar­der com­ment sont bâtis les tem­plates par défaut de Pan­doc, de manière à vous en ins­pi­rer.

La biblio­gra­phie (et pro­duc­tion finale)

La biblio­gra­phie peut être trai­tée dif­fé­rem­ment selon votre for­mat de sor­tie. Quoiqu’il en soit, pour com­men­cer, vous devez pro­duire un fichier de biblio­gra­phie au for­mat bib­tex (.bib).

Dans les com­mandes pan­doc vous devrez ren­sei­gner ce fichier avec

--bibliography=nomdufichier.bib

Et dans votre docu­ment Mark­down, vous pas­sez les réfé­rences ain­si, avec leurs iden­ti­fiants :

Comme le dit Dupont [@dupont1950, p. 15].
Si nous marchons nous ne dormons pas [@Martin1985; @Dupont1950].

Si vous pro­dui­sez un docu­ment LaTeX, le mieux sera d’utiliser l’option --biblatex ce qui aura pour effet de géné­rer la com­mande bibla­tex pour trai­ter la biblio­gra­phie. Par exemple :

pandoc --bibliography=nomdufichier.bib --latex-engine=xelatex mondoc.md -o sortie.tex

Mais l’objet de cet article est de vous aider à pro­duire des docu­ments de manière auto­ma­ti­sée. Voi­ci com­ment pro­cé­der pour pro­duire un docu­ment PDF ou HTML dis­po­sant d’une biblio­gra­phie (et donc d’une liste biblio­gra­phique).

Il faut pour cela uti­li­ser l’interpréteur citeproc (à ins­tal­ler en plus de pan­doc) et un fichier CSL (Cita­tion Style Lan­guage). Le pre­mier per­met d’interpréter les fichiers CSL qui sont en fait des styles de biblio­gra­phie. Vous pou­vez trou­ver un réper­toire de ces fichiers CSL (prêts à l’emploi ou que vous pou­vez modi­fier) dans le dépôt Zote­ro, un logi­ciel de ges­tion biblio­gra­phique.

Une fois votre fichier CSL prêt, vous pou­vez pro­duire :

 pandoc --filter pandoc-citeproc --bibliography=mabiblio.bib --csl=monstylebiblio.csl -s --toc --number-section --template template.html --css template.css masource.md -o sortie.html

Ce qui per­met­tra de pro­duire un docu­ment HTML (stan­da­lone), avec une table des matières, des sec­tions numé­ro­tées, basé sur un modèle HTML et un fichier de style CSS, une biblio­gra­phie trai­tée dans le texte et pré­sente à la fin selon le fichier de style biblio­gra­phique choi­si.

Astuce : pour intro­duire la biblio­gra­phie, lais­sez à la fin de votre docu­ment mark­down un titre comme # Bibliographie.

pandoc --filter pandoc-citeproc --bibliography=mabiblio.bib --csl=monstylebiblio.csl -s --latex-engine=xelatex --toc --number-section -colorlinks masource.md -o sortie.pdf

Ce qui per­met­tra de pro­duire un docu­ment PDF, trai­té par XeLa­TeX, avec une table des matières, des sec­tions numé­ro­tées, des liens colo­rés, une biblio­gra­phie trai­tée dans le texte et pré­sente à la fin selon le fichier de style biblio­gra­phique choi­si.

Pro­duc­tion finale

Si vous n’avez pas de biblio­gra­phie à gérer, vous pou­vez vous lan­cer dans la pro­duc­tion de docu­ments dif­fé­rents à par­tir d’un seul fichier Mark­down.

Pro­dui­sez un fichier .ODT (ou Docx) puis appli­quez vos styles avec LibreOf­fice (ou MSWord). C’est la solu­tion la plus simple : en fait pan­doc pro­duit des styles que vous pou­vez modi­fier ou car­ré­ment écra­ser avec un modèle (LibreOf­fice ou Word) par la suite.

pandoc masource.md -o sortie.odt

Pro­dui­sez un fichier .tex prêt à l’emploi.

pandoc masource.md -o sortie.tex

Pro­dui­sez un docu­ment HTML avec un modèle et un fichier de style, une table des matières, des sec­tions numé­ro­tées.

 pandoc -s --toc --number-section --template template.html --css template.css masource.md -o sortie.html

Pro­dui­sez un beau PDF (tra­vaillé avec LaTeX), avec un modèle pré­pa­ré à l’avance (et dans lequel vous aurez pris le temps d’inclure les mac­kages à uti­li­ser, et tout ce que vous vou­lez dans l’en-tête) :

pandoc -s --latex-engine=xelatex --template template.latex --toc --number-section -colorlinks masource.md -o sortie.pdf

En somme, il peut être par­ti­cu­liè­re­ment utile de vous pré­pa­rer à l’avance quelques modèles (en par­tant des modèles par défaut de pan­doc), même sans for­cé­ment y inté­grer toutes les options. Selon les types de docu­ments que vous pro­dui­sez, vous pour­rez les géné­rer très vite.

Pour ce qui concerne les sor­ties des­ti­nées à un for­mat comme ODT ou Docx, le mieux est encore de pré­pa­rer un modèle qui écra­se­ra les styles du fichier de sor­tie.

Conclu­sion

Même sans connaître toutes les pos­si­bi­li­tés offertes par Pan­doc, vous voi­ci désor­mais en mesure de pro­duire un docu­ment cen­sé être tra­vaillé sous dif­fé­rents for­mats. Ceci est par­ti­cu­liè­re­ment utile si vous êtes cen­sé récu­pé­rer des docu­ments en pro­ve­nance de dif­fé­rentes sources pour les mettre en page et les dif­fu­ser : il est plus facile de deman­der à vos contri­bu­teurs de rédi­ger en Mark­down voire de rédi­ger un texte sans style quitte à ce que vous les repas­siez vous-même en Mark­down. De cette manière il vous sera ensuite très facile de publier dif­fé­rentes ver­sions de ces textes adap­tées aux mode de dif­fu­sions : pour le web, une ver­sion HTML, pour l’impression, une ver­sion PDF (LaTeX), etc.

Bien enten­du, tra­vailler à un bas niveau de mise en page, comme le veut l’usage du Mark­down, néces­site de faire des choix, en par­ti­cu­lier savoir à l’avance vers quel(s) format(s) vous vou­lez conver­tir vos docu­ments. Si vous êtes ame­né à inté­grer des élé­ments de HTML ou de LaTeX dans vos docu­ments Mark­down, faites-le en connais­sance de cause.

En revanche les options de Pan­doc étant nom­breuses, et une fois affi­nées avec des fichiers de style, vos docu­ments seront non seule­ment rapides à pro­duire mais ils béné­fi­cie­ront de mul­tiples manières de les com­pi­ler pour des résul­tats dif­fé­rents.

De manière géné­rale, le Mark­down per­met d’écrire très vite des conte­nus avec un mini­mum de com­mandes. À cer­tains aspects, c’est sans doute le seul for­mat qui per­met d’écrire au kilo­mètre, avec un mini­mum d’informations de mise en page, ce qui per­met de se concen­trer exclu­si­ve­ment sur le conte­nu. Pan­doc et l’art de créer des styles feront le reste.

Christophe

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