Skip to content

Add support for Mermaid diagrams rendering in PDF output#3

Open
Tr8ch wants to merge 1 commit into
atlekbai:mainfrom
Tr8ch:feat/mermaid
Open

Add support for Mermaid diagrams rendering in PDF output#3
Tr8ch wants to merge 1 commit into
atlekbai:mainfrom
Tr8ch:feat/mermaid

Conversation

@Tr8ch

@Tr8ch Tr8ch commented May 5, 2026

Copy link
Copy Markdown

Summary

Mermaid blocks now render as diagrams in the PDF instead of plain code.

The preprocessor catches ```mermaid ``` fences before markdown runs and replaces each one with a base64 PNG <img>.

Renderers, tried in this order:

  1. mmdc (mermaid-cli) if it's on $PATH — works offline.
  2. mermaid.ink as the network fallback.

If both fail, the fence is left as-is, so a missing mmdc or no internet won't break the conversion. Set GHPDF_MERMAID_OFFLINE=1 to skip the network step.

I started with inline SVG. It looked clean for a 3-node flowchart and fell apart on anything real: Mermaid positions labels through HTML inside <foreignObject>, and WeasyPrint doesn't run an HTML engine inside SVG. Node labels came out blank, erDiagram columns piled on top of each other, long edge labels in stateDiagram-v2 ran into their neighbours. Rasterizing in Chromium (what mmdc and mermaid.ink do internally) skips that whole problem. I'm using scale 3, which is enough for A4 without making the PDF huge.

For offline use:

bash npm install -g @mermaid-js/mermaid-cli # or: brew install mermaid-cli ​

@Tr8ch Tr8ch changed the title feat: add support for Mermaid diagrams rendering in PDF output Add support for Mermaid diagrams rendering in PDF output May 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant