Exporter en PDF depuis Obsidian : gérer les références bibliographiques et les liens internes avec Pandoc

Depuis février 2020, j’utilise Obsidian pour gérer toutes mes notes de lecture et les fichiers où je consigne mes réflexions, des traces de mon parcours intellectuel et de mes apprentissages. Obsidian permet de lier chaque nouvelle note aux précédentes, favorisant ainsi des rencontres entre des concepts différents, des secteurs d’étude que je n’aurais pas pensé à croiser de prime abord. On reconnaît là le profit qu’on peut tirer de la méthode Zettelkasten sur laquelle le web permet de disposer d’une littérature désormais abondante.

Obsidian n’était pas un choix évident pour moi, car ce logiciel n’est pas libre. Avec l’aide d’un ami co-concepteur du logiciel org-roam (en référence au logiciel propriétaire et payant Roam), je me suis d’abord tourné vers cet outil conçu pour fonctionner avec l’éditeur emacs et org-mode. En dépit de l’aide précieuse de cet ami aux moments cruciaux de ma prise en main d’org-roam, je me suis peu à peu éloigné d’emacs trouvant que sans doute « la voie est libre » mais la courbe d’apprentissage un peu longue et pour commencer un peu haute. J’aurais sans doute persévéré, si de nouveaux logiciels comme Obsidian et Zettlr n’étaient pas venus à ma connaissance grâce à un doctorant américain qui en faisait la promotion sur Twitter.

Obsidian et le plugin d’export pandoc-obsidian

Ce post toutefois n’est pas destiné à présenter mon usage d’Obsidian mais à traiter le problème de l’export en PDF d’un texte en markdown (puisqu’Obsidian comme Zettlr ou encore Roam utilisent cette syntaxe). Je renoue avec un thème dont j’ai déjà traité sur ce blog, mais cette fois en partant d’Obsidian et non de l’éditeur Atom.

J’apprécie qu’Obsidian me permette de jeter très rapidement quelques notes structurées dans un fichier en markdown et de les relier très facilement aux précédentes. Mais dans le cas où ce fichier prendrait de l’ampleur et que j’y ajoute des références bibliographiques, des schémas, des images, voire du code, je souhaiterais pouvoir en faire un export sous la forme d’un PDF ou d’une page web (dans ce ce dernier cas, une page web accessible en ligne depuis un site statique comme Netlify ou Jekyll).

Ce post se concentre sur l’export en PDF.

Obsidian dispose d’une fonctionnalité toute simple d’export en PDF : tout fichier peut être exporté en PDF en un clic ou bien avec le raccourci-clavier de son choix qu’on aura défini pour cette fonction. La présentation finale du PDF peut-être modifiée au moyen d’un template (css) qu’on peut créer dans Obsidian.

Toutefois lorsqu’on commence à sourcer ses articles à partir de sa bibliothèque Zotero au moyen de l’indispensable plugin Citations, cette fonction basique d’export de suffit plus. Le PDF produit ne comportera aucune des références insérée avec Citations.

Dans ce cas, une alternative s’offre à nous :

• Ou bien nous nous en remettons à un autre plugin communautaire intitulé pandoc-obsidian
• Ou bien nous convertissons depuis le répertoire source de nos notes celle qui nous intéresse au moyen de Pandoc. Pour rappel, ce dernier logiciel ne dispose pas d’interface graphique et fonctionne uniquement en lignes de commande exécutées sur un terminal. Lorsque j’utilise mon ordinateur sous Windows, j’utilise l’interpréteur de commandes Powershell. On peut l’ouvrir très facilement : shift + clic droit pour l’ouvrir dans le répertoire où l’on se trouve.

J’ai d’abord opté pour la première solution, à partir du mois de juillet. Oliver Balfour, le concepteur de pandoc-obsidian, était en train de perfectionner son plugin et avec quelques autres, nous lui avons fait remonter sur Github des propositions d’amélioration ou des dysfonctionnements que nous avions pu observer.

En ajoutant quelques arguments supplémentaires nécessaires pour générer la bibliographie contenue dans l’article, comme le filtre citeproc ou bien le chemin vers le fichier-source de la biblio (car j’ai remarqué qu’Obsidian ne le traite pas correctement quand il est indiqué dans l’entête YAML), on arrive à avoir un rendu qui se rapproche de ce que l’on souhaite obtenir.

les références insérées dans le texte avec Citations (qui fait le lien avec Zotero) sont bien transformées en appels de citations, la bibliographie apparaît bien à la fin du fichier MAIS les wikiliens qui caractérisent Obsidian sont toujours là. Pour les éliminer, en théorie, il serait nécessaire de les supprimer dans une copie du fichier source de la note et ensuite d’exporter cette copie en PDF avec Pandoc-Plugin.

Les Wikiliens dans Obsidian (et comment les gérer avec Pandoc)

A ce stade, une explication s’impose : qu’est-ce qu’un wikilien (wikilink)?

La syntaxe Markdown prévoir qu’un lien s’écrive de cette manière : [texte du lien](URL ou chemin vers le fichier)

Toutefois, dans Obsidian, lorsque le lien pointe vers une autre note du répertoire, Obsidian permet de simplifier l’écriture de ce lien de la manière suivante : [[lien vers une autre note]]

C’est extrêmement pratique et rapide : on n’a pas besoin de se préoccuper d’indiquer un chemin ou un texte de lien. On reconnaît dans cette syntaxe les liens qui unissent les articles de Wikipédia entre eux, d’où cette appellation de wikiliens.

Toutefois, comme l’a fait remarquer plusieurs fois Oliver Balfour, son plugin ne permet pas de gérer à la fois le module Citations propre à Obsidian et qui incruste les clés des références sous la forme de Wikiliens et l’export d’un texte avec sa bibliographie selon les règles habituelles de Pandoc. Or il nous faut à la fois Citations et les Wikiliens dans Obsidian et un export propre (où les wikiliens se transforment en texte) vers un document PDF.

Moonbase59 explique assez clairement en quoi l’usage des wikiliens est à la fois un atout et une limite ; un atout tant qu’on reste dans Obsidian, une limite quand on commence à vouloir utiliser d’autres éditeurs en markdown ou bien un gestionnaire de conversions de fichiers comme pandoc.

Pour traiter ce problème des marques des wikiliens qui persistent dans le PDF obtenu avec pandoc, et en m’inspirant de ce que j’avais appris cet été en suivant un cours en ligne sur la gestion d’un serveur sur GNU/Linux, je me suis mis à imaginer une chaîne de commandes sur Powershell qui puisse réaliser les opérations suivantes :

• sélection d’une note à convertir
• suppression dans le contenu de cette note des balises qui encadrent les wikiliens ([[ et ]]) et envoi du texte résultant de cette suppression dans un autre répertoire
• conversion du document résultant de cette opération en PDF avec Pandoc.

Mes premiers pas avec Powershell

Ne connaissant rien à Powershell, je me suis mis à interroger la documentation en ligne pléthorique qu’on trouve à ce sujet sur le web et en l’espace d’une heure ou deux, je suis arrivé à réaliser cette suite d’opérations :

# sélection du fichier à convertir
$filename = Read-Host "entrer le nom du fichier sans l'extension"
# suppression de la suite de caractères [[ et ]], copie du résultat dans un dossier qui devra être préalablement créé (mypdf)
(Get-content .\$filename.md -Raw).replace("[[","").replace("]]","") | Set-content mypdf\$filename.md
# export de cette copie en markdown purgée des wikilinks sous forme de document PDF dans mypdf. Le pdf créé prend le nom du fichier d'origine. Seul l'extension du fichier change (.md -> /pdf )
pandoc mypdf\$filename.md --bibliography .\biblio\mylibrary.bib --csl .\csl\ieee.csl --pdf-engine=xelatex --citeproc -f markdown+smart -o mypdf\$filename.pdf
# suppression de la copie en markdown dans mypdf
Remove-Item mypdf\$filename.md

Ce code fonctionne si :

• on a bien pandoc et un éditeur LaTeX installés sur sa machine
• si dans son répertoire de notes dans Obsidian on dispose d’un dossier csl où l’on a préalablement chargé la feuille de style ieee.csl
• si on a préalablement dans le répertoire de notes un dossier intitulé mypdf où l’on va retrouver le produit de notre export de la note avec pandoc
• si on a ses références bibliographiques dans un fichier mylibrary.bib dans un répertoire biblio.
• (et bien sûr si on travaille avec un ordinateur Windows et le terminal de commandes Powershell)

A partir de ce premier succès, je n’ai eu de cesse les jours suivants d’essayer d’améliorer ce code en y ajoutant des fonctionnalités particulières :

• Si le répertoire mypdf n’existe pas, peut-on le créer instantanément ? (#1)
• Supposons que je ne dispose pas déjà d’un dossier intitulé csl où je range mes feuilles de style, l’application peut-elle me créer le dossier et me charger automatiquement au moins trois feuilles de styles puis me donner à choisir l’une des trois (#2)
• Peut-on à l’occasion proposer à l’utilisateur de charger dans le dossier csl une feuille de style qu’il aurait quelque part dans ses fichiers (sur son bureau par exemple)(#3)
• Supposons que je ne dipose pas déjà d’un dossier intitulé mypdf, ce dossier peut-il être créé à la volée ? (#4)
• Peut-on demander à l’utilisateur de sélectionner le fichier qui contient la biblio (.bib) plutôt que lui demander de modifier le code en remplaçant le chemin .\biblio\mylibrary.bib par le bon chemin et le bon fichier (#5)
• Peut-on demander seulement à l’utilisateur de sélectionner avec l’explorateur Windows le dossier où se trouvent les notes qu’il veut exporter en PDF ? (cela permettra ensuite de travailler avec des chemins relatifs .\mypdf ou .\csl ) (#6)
• Peut-on présenter le tout comme un fichier exécutable à des utilisateurs qui n’ont pas l’habitude de faire fonctionner des scripts depuis un interpréteur de commandes (#7)
• Peut-on traduire ces commandes écrites pour powershell en commandes interprétables par un ordinateur fonctionnant sur GNU/Linux ? (#8)

cela donne pour l’instant le programme suivant :

# présentation du logiciel
Write-Host "ce programme va vous permettre de convertir une note de votre bibliothèque  de notes en PDF en générant la bibliographie qui lui est liée" -ForegroundColor blue
# pause pour permettre à l'utilisateur de lire la présentation
read-host "appuyer sur Entrée pour continuer..."
# sélection du répertoire de notes de l'utilisateur avec l'explorateur Windows
Write-Host "veuillez sélectionner le répertoire qui contient vos notes" -ForegroundColor Green
Add-Type -AssemblyName System.Windows.Forms
$browser = New-Object System.Windows.Forms.FolderBrowserDialog
$null = $browser.ShowDialog()
$path = $browser.SelectedPath
Set-Location $path
# si le dossier mypdf n'existe pas encore dans le répertoire de notes, il sera créé automatiquement
If(!(test-path $path\mypdf))
{
      New-Item -ItemType Directory -Force -Path $path\mypdf
}
# sélection de la note à exporter en PDF
$filename = Read-Host "entrer le nom du fichier sans l'extension"
# si le dossier mypdf n'existe pas encore dans le répertoire de notes, il sera créé automatiquement
# dans ce cas, on y chargera automatiquement depuis le site de Zotero trois feuilles de style (ieee, nature et Vancouver)
If(!(test-path $path\csl))
{
      New-Item -ItemType Directory -Force -Path $path\csl
Invoke-WebRequest -Uri "https://www.zotero.org/styles/vancouver" -OutFile $path\csl\vancouver.csl
Invoke-WebRequest -Uri "https://www.zotero.org/styles/ieee" -OutFile $path\csl\ieee.csl
Invoke-WebRequest -Uri "https://www.zotero.org/styles/nature" -OutFile $path\csl\nature.csl

      Write-Host "voici la liste des styles disponibles" -ForegroundColor Green
      Get-ChildItem .\csl\ -name
}
else
{
Write-Host "voici la liste des styles disponibles" -ForegroundColor Green
Get-ChildItem .\csl\ -name
}
# choix du style entre ceux présents dans le dossier csl
$stylename = Read-Host "entrer le nom du style"
# conversion de la note avec pandoc et suppression des wikiliens
(Get-content .\$filename.md -Raw).replace("[[","").replace("]]","") | Set-content mypdf\$filename.md
pandoc mypdf\$filename.md --bibliography .\biblio\mylibrary.bib --csl .\csl\$stylename --pdf-engine=xelatex --citeproc -f markdown+smart -o mypdf\$filename.pdf
# suppression du fichier markdown dans mypdf correspondant à la note exportée en pdf
Remove-Item mypdf\$filename.md

Ce script enregistré en format .ps1 sera ensuite converti en .exe avec un utilitaire trouvé en ligne et téléchargé « Ps1 to exe« .

Les points #1, #2, #4, #6 et #7 sont donc déjà réalisés dans le programme ci-dessus.

Dans la résolution du point #3 je me heurte au fait que le programme ne peut pas faire une copie du fichier csl présent dans un dossier du répertoire de notes pour des raisons de paramétrage de droits que je n’ai pas encore bien comprises.

Quant au point #5, cela ne devrait pas poser de difficulté. Mais le mieux serait encore de définir le chemin vers la biblio dans l’entête YAML du fichier à convertir. Je trouverais cela beaucoup plus satisfaisant, mais en dépit de mes tentatives, ça ne fonctionne pas.

Pour le point #8, j’attendrais d’avoir un peu de temps pour tout réécrire sous la forme d’un programme compatible avec GNU/Linux.

Pour moi qui n’avais jamais rien développé de programme original en powershell auparavant (ni dans un autre langage d’ailleurs), ce simple script issu d’un besoin très particulier m’a valu des heures de recherche. Il m’a fallu me lever une heure plus tôt pendant une semaine et m’endormir une heure plus tard pour y travailler. Il a d’ailleurs été assez difficile ces derniers jours de délaisser le programme en cours de construction pour revenir à mes affaires quotidiennes de bibliothécaire, mais ça a été un travail aussi réjouissant et instructif que prenant et je suis très content d’y avoir consacré tout ce temps d’apprentissage, même si le résultat sera jugé banal pour les personnes qui connaissent powershell et ne sera utile qu’aux très rares utilisateurs d’obsidian qui se seront posé les mêmes questions que moi.