Atelier de formation doctorale
11 décembre 2025
Ce guide présente les principes du texte simple, de la syntaxe markdown et de la conversion de fichiers avec le logiciel Pandoc. Après une présentation des potentialités du format markdown, nous aborderons le traitement des références bibliographiques lors de la conversion de fichiers. Nous verrons ensuite quel rôle peut jouer Zotero dans l’ajout de références dans un éditeur en markdown et en \(\LaTeX\).
Les fichiers source de ce guide se trouvent un entrepôt public de Framagit, la forge de Framasoft.
Word, logiciel propriétaire de la suite Microsoft Office et Writer, son équivalent libre composante de la suite open source LibreOffice sont des traitements de texte. Un traitement de texte formate le texte a priori et réalise des opérations de manière opaque pour l’usager. Chaque fichier est constitué de différentes couches et sous-fichiers. Les textes issus des traitements de texte ne sont interopérables avec d’autres types de fichiers. Ils ne peuvent être facilement traités en masse car dépourvus d’un assez grand nombre de champs balisés. Les citations internes au texte ni les références ne sont distingués du reste du texte, ce qui fait dire à Mario Vitali Rosati que dans un monde où les publications sont lues et connectées les uns aux autres par des ordinateurs, ce défaut de balisage est un problème majeur. (1).
Par ailleurs, le texte simple sur laquelle on peut appliquer soit le système de balisage du markdown ou celui du LaTeX est globalement plus sobre et plus résistant aux évolutions des formats que les standards du type .doc ou .docx menacés chacun par une obsolescence logicielle plus rapide.
En raison de l’opacité de ces actions réalisées par le traitement de texte, régler finement certains détails de mise en page s’avère ardu, par exemple lorsqu’il s’agit d’agencer le texte à l’image.
Selon Daphné Mathelier, le markdown en tant qu’écriture numérique simplifiée et académique permet aux chercheurs et chercheuses de consacrer plus de temps de réflexion à leur sujet de recherche qu’à la manière de le mettre en forme. Le markdown permet une forme de minimalisme éditorial en même temps qu’un gain de sobriété attentionnelle (2 )
Utiliser Markdown […] permet de revenir à des méthodes qui vont à l’essentiel en faisant les choses dans l’ordre – écrire, illustrer, éditer puis publier – de manière durable et sans perte de temps et d’énergie inutiles
De plus dans certaines disciplines, l’inscription de code source, de figures générées automatiquement depuis des jeux de données ou de formules mathématiques rend nécessaire le recours à d’autres outils que les traitements de texte. Si le langage de programmation \(\LaTeX\) présente une courbe d’apprentissage assez raide, il est possible de passer par une syntaxe intermédiaire et simple à apprendre le markdown. Cette syntaxe peut accueillir des éléments en \(\LaTeX\) ou en html. Par exemple, l’affichage de l’image ci-dessous est provoquée par une ligne de html :
<img src="images/word_image.jpg" width="400px">Tandis que dans ce document en markdown, la graphie de LaTeX est obtenue au moyen de la commande latex $\LaTeX$
Le reste de cette page a été rédigée en markdown
Chaque système d’exploitation comporte au moins un éditeur de texte, le bloc-note disponible dans l’ensemble des applications pré-installées. Il suffit d’écrire un texte et d’enregistrer le fichier avec une extension en .md : le document sera lu et interprété comme un document en markdown. Bien sûr, il est utile ensuite, mais relativement rapide d’apprendre à formater un texte en markdown pour pouvoir ensuite le convertir dans le format de son choix.
D’autres éditeurs, plus complexes, peuvent être installés, non seulement pour éditer du texte en markdown, mais aussi du code source dans différents langages informatiques. Citons-en quelques un parmi les plus connus :
Pour afficher des citations dans un texte, on a besoin de compiler plusieurs fichiers :
Le résultat de cette compilation avec sa bibliographie bien ordonnée dans le style choisi apparaîtra dans un quatrième document.
ce fichier de sortie pourra être en format opendocument (.odt), word, html, pdf, etc.
L’outil qui va nous servir à compiler ces trois documents pour obtenir le quatrième peut être téléchargé en ligne et installé sur un ordinateur. Il s’agit de Pandoc. Pandoc est également intégré à de nombreux éditeurs utilisables en ligne (comme Stylo, un éditeur en markdonw ou Overleaf, un éditeur en \(\LaTeX\) ) ou localement (comme R avec Rstudio)
Pour insérer une citation dans le texte, nous avons besoin de deux choses : le signe @ et une clé de citation unique pour chaque item présent dans le fichier bibtex
Par exemple, si nous reprenons une phrase présente ci-dessus :
il ne balise pas assez le texte (titre, sous-titre, notes, citation, références), il ne balise pas non plus assez les références.
Dans un monde où les publications sont lues et connectées les uns aux autres par des ordinateurs, ce défaut de balisage est un problème @vitali-rosatiChercheursSHSSaventils2018. Le @ renvoie à l’entrée suivante dans le fichier bibtex (.bib) qui contient la biblio :
@article{vitali-rosatiChercheursSHSSaventils2018,
title = {Les chercheurs en {SHS} savent-ils écrire ?},
url = {http://theconversation.com/les-chercheurs-en-shs-savent-ils-ecrire-93024},
abstract = {Il est nécessaire que les chercheurs aient des compétences techniques. Ceux qui ne les ont pas, ne savent tout simplement pas écrire et ne doivent donc pas le faire.},
language = {en},
urldate = {2022-01-20},
journal = {The Conversation},
author = {Vitali-Rosati, Marcello},
month = mar,
year = {2018},
file = {Snapshot:/home/dbelveze/Zotero/storage/C2YRJG79/les-chercheurs-en-shs-savent-ils-ecrire-93024.html:text/html},
}La clé de citation unique ici est vitali-rosatiChercheursSHSSaventils2018, une sorte de condensé entre le nom de l’auteur, le nom du titre et l’année de publication. Le plugin BetterBibTex une fois installé dans Zotero a pour rôle d’ajouter à toutes les références déjà présentes dans les collections et celles à venir ce type d’identifiant unique. BetterBibTex permet d’ailleurs d’en changer la composition, s’il y a besoin de le faire, ce qui n’est généralement pas le cas. Mais n’anticipons pas, nous verrons comment cela se passe du côté de Zotero plus tard, pour l’instant, contentons-nous de parler de la conversion des documents en markdown qui comportent des références bibliographiques.
Le convertisseur universel Pandoc va nous permettre de convertir un fichier de markdown vers un autre format de sorte que le format de destination comporte une bibliographie en bonne et due forme. Pandoc est développé et maintenu par John MacFarlane. C’est une librairie développée en Haskell et distribué sous une licence GPL.
On parle d’un convertisseur universel mais avec une limite importante : on ne peut pas convertir un pdf en document inscriptible. Pour convertir un texte écrit en markdown afin d’obtenir un texte en html, opendocument, ou word, Pandoc et son composant citeproc suffisent (citeproc pour gérer la bibliographie présente dans le document source). En revanche, la conversion depuis markdown via Pandoc vers du pdf suppose l’usage d’un programme intégré aux distributions de \(\LaTeX\) (pdflatex ou xelatex selon la distribution). Installer une distribution de \(\LaTeX\) n’est pas trivial. Il s’agit d’un éditeur qui comporte un grand nombre de librairies associées et le temps d’installation peut être assez long selon la vitesse de votre ordinateur. Anticipez cette étape autant que possible.
Pandoc ne dispose pas d’interface graphique, cet outil s’utilise en lignes de commande depuis un terminal ou bien peut être intégré à des applications (fichiers d’intégration continue, version pour Python : pypandoc, intégré à R, à Stylo, etc.)
Installer Pandoc sur votre système
Télécharger les documents suivants (en cliquant sur les liens)
Sous Windows : appuyer sur maj et faire en même temps un clic droit pour ouvrir un menu contextuel à l’endroit où on veut faire la conversion. Dans le menu contextuel, choisir “Ouvrir Powershell ici” Sous Linux : appuyer simultanément sur Ctrl+shift+T Sous MacOs : ⌘ command + ESPACE
Note : pour coller une chaîne de caractères dans un terminal : appuyer sur Ctrl+shift+V (pour copier : Ctrl+shift+C)
Dans la perspective d’une conversion d’un fichier markdown vers un format PDF, la commande Pandoc à inscrire dans le terminal doit comporter les informations suivantes :
-f markdown)-t pdf )La commande peut s’écrire sur une ligne ou bien, pour plus de lisibilité, peut être fractionnée dans le terminal avec un \ (slash) à chaque ligne.
pandoc input.md \
-f markdown \
--bibliography=references.bib \
--csl=apa.csl \
--citeproc \
--pdf-engine=xelatex \
-t pdf \
-o from_md.pdfOuvrir un terminal dans le dossier où vous avez téléchargé les fichiers mentionnés plus haut. Copier cette commande dans votre terminal Appuyer sur ENTREE.
Vous devriez obtenir un document pdf (from_pdf) équivalent à celui-ci
Essayez cette fois avec un fichier \(\LaTeX\) en sortie
pandoc input.md \
-f markdown \
--bibliography=biblio.bib \
--csl=apa.csl \
--citeproc \
--pdf-engine=xelatex \
-o input.texCela ne concerne par prioriairement la bibliographie, mais notez que Pandoc peut adjoindre à la conversion bien d’autres éléments de style, notamment il peut prendre en compte une feuille de style complète. Voici comment appliquer cette feuille de style que vous pouvez télécharger comme les autres documents pour le déposer dans le même répertoire.
pandoc input.md \
--standalone \
-H example.css \
--bibliography=references.bib \
--csl=apa.csl \
--citeproc \
--pdf-engine=xelatex \
-o input.htmlL’ajout de -H example.css permet de faire le lien avec la feuille de style example.css qui modifie entre autres la couleur de fonds d’écran.
Zotero est un logiciel qui rend possible la création de notes en mardown. Jusqu’à la version 6, elles étaient exportables en markdown au moyen d’un plugin additionnel (MDnotes qui n’a pas été réécrit pour la version 7 de Zotero) ; aujourd’hui, cette fonctionnalité est au coeur de Zotero. Lorsqu’on fait un clic droit sur une note, on peut l’exporter en HTML ou en markdown. Certains plugins permettent d’inclure Zotero dans un environnement de travail qui comporte l’écriture en markdown de notes de lecture liées à des références présentes dans Zotero. C’est le cas notamment de MarkDB-connect.
De façon basique, on va expliquer ci-dessous comment garder à jour dans son environnement de travail des listes de références issues de Zotero au moyen du plugin BetterBibTex.
Le plugin BetterBibTex (BBT) est continuellement mis à jour de version en version pour permettre à tous les utilisateurs et utilisatrices d’éditeurs de texte de continuer à utiliser Zotero dans leur environnement de travail. BBT permet un export en Bibtex de n’importe quelle référence (en mode quick copy) dans un fichier bibtex déjà constitué. Mais il rend aussi possible de synchroniser une collection avec un fichier bibtex en local, de sorte que chaque fois qu’on ajoute une référence dans la collection, cela va générer automatiquement une entrée supplémentaire dans le fichier .bib et donc une ajouter une référence mobilisable de plus dans l’éditeur de texte.
BBT se télécharge comme n’importe quel plugin pour Zotero :
Une colonne sera ajoutée dans laquelle on trouvera une clé de citation (voir plus haut) pour chaque référence.
Une foix BetterBibTex installé, lorsqu’on clique-droit sur une collection et qu’on choisit d’exporter cette collection, on dispose désormais de nouveaux formats d’export en particulier le format BetterbibLatex. Si on sélectionne ce format et qu’on prend soin de cocher l’option “garder à jour” (keep updated dans la version anglaise de Zotero), on n’a plus qu’à l’emplacement pour relier le texte à éditer et la bibliographie correspondant à ce document.
A partir de ce moment on peut continuer d’utiliser Zotero pour enrichir la collection source, la mise à jour se fera automatiquement dans le fichier bibtex de destination.
C’est le principe général de fonctionnement de Zotero avec les éditeurs de texte au moyen du plugin BetterBibTex ; en fonction des éditeurs, il peut y avoir quelques différences ou quelques paramètres en plus à revoir. Passons en revue quelques éditeurs populaires et commençons par ceux qui sont spécialisés dans le format markdown.
Obsidian est un outil de gestion de notes très populaire qui intègre un éditeur en markdown. Contrairement à des logiciels comme Evernote ou Roam, Obsidian, bien que propriétaire, permet d’éditer et de conserver ses notes en local, sur son ordinateur. Plusieurs plugins existent pour intégrer Zotero dans un workflow éditorial dont Obsidian serait la pièce maîntresse. Nous en retenons deux qui nous paraissent assez robustes : Citation et Pandoc Reference List.
Ils ne sont pas à mettre sur le même plan : Citation fait l’essentiel du travail décrit plus haut : ce plugin d’Obsidian permet de puiser dans une collection de Zotero (ou l’ensemble de la bibliothèque) les références qui viendront illustrer les notes prises dans ce gestionnaire. Si on veut en plus afficher les réfrences bibliographiques des textes cités, et cela dans l’éditeur Obsidian lui-même, ou copier ces références depuis l’éditeur dans le style choisi pour les faire figurer en fin de note, on peut utiliser en plus le deuxième Plugin, Pandoc References List.
Il est bien entendu nécessaire d’installer puis d’activer ces plugins dans Obsidian. Il s’agit de plugins communautaires, il faut auparavant avoir donné la permission à Obsidian de charger ce type de plugins, c’est une permission qui se donne une fois pour toutes.
Voici comment on règle les paramètres du plugin Citation dans Obisidian :
Citation Database format : bibtex
Citation database path : lien absolu vers le fichier .bib
Literature Notes Folder : nom_du_dossier
Literature Note Template : @{{citekey}}
Literature Note Content Template :
title: "{{title}}"
author: {{authorString}}
year: {{year}}
publisher: {{publisher}}
publication: {{containerTitle}}
url: {{URL}}
note: {{note}}
doi: {{doi}}
tags: [ref]Bien sûr, on peut changer la liste des variables de ce modèle de notes à loisir : enlever le champ {{doi}}, lui substituer le champ {{eventPlace}} si on constitue une collection d’actes de conférence par exemple…
Pandoc Reference List demande également quelques paramétrages, notamment le lien avec le fichier exécutable de Pandoc là où il se trouve sur l’ordinateur (Fallback Path To pandoc).
Pour obtenir le lien absolu vers cet exécutable, on peut utiliser les commandes suivantes dans un terminal : $ whereis pandoc (GNU/Linux) , C:\> where pandoc.exe(pour windows). De la même manière, fournir le lien vers le fichier source qui contient les références (“Path to bibliography file”), c’est à dire le chemin absolu (depuis le Home de l’usager) vers le fichier .bib (même lien que pour Citation) Pour le reste, les valeurs à définir sont : Pull bibliography from Zotero : on
zotero port : 23119
Après avoir vu comment les bibliographies issues de Zotero étaient générées dans des documents en markdown compilés sous la forme de documents en word, opendocument, pdf, html ou autres, nous allons nous intéresser à la manière dont cette compilation se fait dans des éditeurs spécialisés en \(\LaTeX\) ou bien supportant de manière optionnelle l’écriture dans ce langage de programmation.
VSCode est un éditeur de texte développé par Microsoft et qui peut être librement installé sur son ordinateur. Une version libre de cet éditeur existe, VSCodium, dont le fonctionnement est quasi identique. On peut, au moyen d’extensions, éditer du code R ou LaTeX à travers VSCode.
Pour écrire en \(\LaTeX\) depuis VSCode, il est nécessaire de charger le plugin LaTeX Workshop, puis de modifier les paramètres de VSCode. Pour cela, on ouvre la palette de l’éditeur (avec la combinaison de touches Ctrl+Maj+P) puis dans le menu chercher Open User puis le fichier settings.json.
Il reste à copier dans ce fichier settings.json le code suivant :
/* workflow pour la compilation d'un document en LaTeX */
"latex-workshop.latex.recipes": [
{
/* utilisation de biber avec LateX */
"name": "xelatex -> biber -> xelatex*2",
"tools": [
"xelatex", /* génère un document en PDF avec LaTeX en remplaçant les références dans le texte par des points d'interrogation */
"biber", /* parse les références bibliographiques présentes dans le fichier .bib pour leur insertion dans le pdf */
"xelatex", /* place toutes les références parsées à l'étape précédente au bon endroit */
"xelatex" /* refait l'étape précédente pour éviter que l'insertion des références ne perturbe la numérotation des pages */
]
},
],
"latex-workshop.latex.tools": [
{
"name": "pdflatex",
"command": "pdflatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"%DOC%"
]
},
{
"name": "bibtex",
"command": "bibtex",
"args": [
"%DOCFILE%"
]
},
{
/*ajoute une entrée pour biber */
"name": "biber",
"command": "biber",
"args": [
"%DOCFILE%"
]
},
{
"name": "xelatex",
"command": "xelatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"%DOC%"
]
}Ce script se présente comme une “recette” pour compiler un texte source écrit en \(\LaTeX\) en PDF en utilisant au passage des composants de LaTeX : la conversion de base en LaTeX avec xelatex et biber (et ses 4 étapes principales).
La création de compte est gratuite, en revanche, pour synchroniser un projet Overleaf avec Zotero, il faudrait un communautaire. Or l’Université de Rennes n’en dispose pas et ne peut pas en faire bénéficier ses affilié.e.s. Contrairement à ce que nous avons vu plus haut, il n’y a donc pas de possibilité de synchroniser Zotero avec Overleaf : on doit constituer sa bibliothèque de références avec Zotero, puis l’exporter et la charger depuis son envionnement en ligne sur Overleaf. En théorie, on doit recommencer l’opération à chaque fois qu’on ajoute une nouvelle référenceà la collection source.
Il devient rapidement plus simple de faire une copie rapide de la référence ajoutée dans Zotero et de la coller dans le fichier .bib dans Overleaf. Si on veut néanmoins synchroniser l’entrée dans Overleaf de nouvelles références, on peut utiliser la forge github comme intermédiaire, puisque Overleaf peut importer automatiquement toutes les modifications apportées à des fichiers présents sur la forge. Un article du blog de JabRef de décembre 2025 explique comment cela peut se faire Jabref, une solution équivalente à Zotero, également libre. Ce fonctionnement peut être reproduit avec Zotero si on exporte la collection pertinente en format .bib dans un projet git sur sa machine et qu’ensuite on push ce projet vers l’entrepôt github.
Pour n’importe quel éditeur en \(\LaTeX\), le document maître doit comporter dans son entête : - le lien vers le fichier .bib qui contient les références - le lien ou la mention vers le style bibliographique
Pour plus d’information sur les styles bibliographiques utilisables dans Overleaf, se référer au guide de la solution.
Ainsi dans notre exemple input.tex, l’entête - en \(\LaTeX\), l’entête est ce qui précède la balise \begin{document} - sera rédigée comme suit :
\documentclass[12pt]{article} % type de document %
\usepackage[utf8]{inputenc} % package qui gère l'encodage %
\usepackage[T1]{fontenc} % package qui gère les polices %
\usepackage[english]{babel}
\usepackage{csquotes} % affichage des citations dans le texte %
\usepackage{ifpdf,newtxtext,newtxmath} %application de LaTeX pour les PDF, autres packages liés aux polices de caractères %
\usepackage[backend=biber, style=ieee]{biblatex} %lien vers biber, utilisation du style ieee fourni dans la suite LaTeX %
\addbibresource{references.bib} %lien vers le fichier de références%Stylo a été créé par Marcelo Vitali-Rosati pour mettre en oeuvre ses principes d’écriture pour les Sciences Humaines et Sociales (parmi ces principes, nous avons cité au début de ce guide celui du balisage du texte scientifique). Cet outil d’édition en ligne est disponible sur la plateforme Huma-Num, moyennant la création d’un compte individuel (=Human-ID) et permet une élaboration tant individuelle que collaborative d’un texte scientifique. Stylo intègre Pandoc et \(\LaTeX\), par conséquent, il n’est pas nécessaire d’écriture soi-même la commande d’exécution de Pandoc (même si celle-ci est mise à disposition au besoin pour être reproduite ailleurs dans d’autres environnements). Stylo peut être connecté à son compte Zotero en ligne ; précisément, on peut sélectionner une fois les deux comptes joints, la collection de Zotero qui servira à enrichir la bibliographie du texte qu’on est en train d’élaborer sur Stylo.
On peut citer comme exemples d’éditeurs en \(\LaTeX\) TeXStudio ou TeXmaker. Utiliser un éditeur de texte en local ne présente pas le même problème que celui dont nous avons parlé à propos d’Overleaf (synchronisation entre la collection Zotero et le fichier de destination). Toutefois, l’éditeur peut proposer des modes de compilation différents qu’il faut savoir maîtriser (on a vu l’un de ces modes plus haut avec VScode). Il faut inscrire dans les préférences de l’éditeur de texte les étapes de la compilation incluant biber dans la recette de compilation.
Voici comment on peut procéder avec TeXmaker en utilisant biber, à la place de bib(La)Tex pour gérer les références
Dans la console de TeXmaker, aller sur le panneau de configuration des commandes de l’usager (user > user commands > edit user commands)
puis dans Options remplacer bibtex par biber :
(options> Configure TeXmaker > commands) ;
entrer dans le champ ‘Bib(la)tex’ = «/bin/biber» % (vérifier que biber est bien dans le dossier /bin, sinon on peut télécharger et installer cette librairie depuis SourceForge)
Configurer les commandes d’utilisateur pour remplacer la commande bibtex par biber
(cela nécessite que le package biber soit appelé dans l’entête du document)
puis dans le processus de compilation, choisir LaTeX + BibLaTex + LaTeX(x2) + dvips + ps2pdf + see pdf
(options > configure texmaker > Quick build), comme dans l’image ci-dessous :
Naturellement, dans un document markdown, la bibliographie issue de la compilation des références va s’inscrire à la fin du document. On peut l’anticiper en réservant une section Références ou bibliographie (ou ce qu’on veut). En revanche, si on souhaite ajouter des annexes au document ou bien tout autre ajout après la bibliographie, il est nécessaire d’ajouter une balise pour ancrer la biblio dans le texte. Selon les langages, les balises vont être de nature différente.
Cela se fait au moyen d’une balise html pour du markdown
<div id="refs"><div>et avec la balise \printbibliography dans un texte rédigé en \(\LaTeX\)