Retour au blog
Articles

Corriger l’export Mermaid avec Markdown PDF

Vérifier la version du script Mermaid quand les diagrammes disparaissent du PDF.

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 :

text
graph TD
    A --> B
    A --> C
    B --> D
    C --> D

Sur cette page, il apparaît sous forme de diagramme :

ABCD
上方 Mermaid 程式碼對應的流程圖。

L'aperçu de VS Code peut être correct alors que l'exportation en PDF échoue de deux façons :

  1. Le diagramme reste du texte : le PDF contient le bloc Mermaid d'origine, sans rendu graphique.

    text
    graph TD
        A --> B
        A --> C
        B --> D
        C --> D
    
  2. 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 :

text
https://unpkg.com/mermaid/dist/mermaid.min.js

avec:

text
https://unpkg.com/[email protected]/dist/mermaid.js

Et les autres versions ?

Deux discussions GitHub documentent ce problème :

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.