Exporter un document Markdown en PDF depuis VS Code se complique parfois dès qu'il contient un diagramme Mermaid. L'extension Markdown PDF peut afficher le code du diagramme tel quel ou produire une page blanche. Voici les symptômes à reconnaître et un réglage de version à essayer.
Markdown PDF
La page d'extension ressemble à ceci :
Markdown PDF offre plusieurs fonctions pratiques :
- La commande Palette de commandes → Markdown PDF: Export (pdf) lance directement l'exportation. L'extension propose aussi les formats HTML, PNG et JPEG.
- Elle utilise Puppeteer pour convertir le HTML en PDF avec Chrome sans interface graphique. Les formules KaTeX, la coloration du code et les styles CSS peuvent ainsi être conservés.
- L'URL du script Mermaid Server est configurable. C'est le réglage qui nous intéresse ici.
Après l'installation, plusieurs propriétés apparaissent dans settings.json. Cet article se concentre sur markdown-pdf.mermaidServer.
Erreur d'exportation de Mermaid
Prenons ce bloc Mermaid :
graph TD
A --> B
A --> C
B --> D
C --> D
Sur cette page, il apparaît sous forme de diagramme :
L'aperçu de VS Code peut être correct alors que l'exportation en PDF échoue de deux façons :
-
Le diagramme reste du texte : le PDF contient le bloc Mermaid d'origine, sans rendu graphique.
graph TD A --> B A --> C B --> D C --> D -
Icône d'erreur ou page blanche : le diagramme n'apparaît pas dans le PDF.
Des signalements font état de problèmes de compatibilité entre Markdown PDF et certaines versions de Mermaid.
Changer l'URL du script Mermaid rétablit le rendu de certains diagrammes, selon la version et le type de diagramme. Vérifiez donc le script chargé lors de l'exportation : un aperçu correct ne garantit pas un PDF correct.
Solution
Dans les paramètres de VS Code, cherchez markdown-pdf.mermaidServer et essayez la version Mermaid 10.3.1 :
Remplacez l'URL par défaut :
https://unpkg.com/mermaid/dist/mermaid.min.js
avec:
https://unpkg.com/[email protected]/dist/mermaid.js
Et les autres versions ?
Deux discussions GitHub documentent ce problème :
- Markdown-pdf: VSCode Mermaid server URL is no longer resolving #312
- [BUG] Mermaid Diagrams Not Rendering in PDF Export #342
On y trouve plusieurs versions de script proposées :
Lors des essais décrits dans l'article d'origine, la version 10.3.1 exportait correctement graph, sequenceDiagram et gantt. Les autres types de diagrammes, dont classDiagram et stateDiagram, n'avaient pas été testés. Avant de modifier un document plus long, exportez un exemple de chaque type utilisé et examinez le PDF.
Les versions de l'extension et de Mermaid ont pu évoluer depuis ces essais. Le PDF généré reste la vérification décisive.
