iTranslated by AI
Released a Plugin to Convert Mermaid Models to SVG in MkDocs
Introduction
MkDocs is a static site generator widely used for creating documentation.
I use MkDocs for my development documentation for two main reasons:
- It allows Mermaid diagrams to be rendered by enabling Markdown extensions.
- It allows the entire site to be exported as a single PDF using the MkDocs to PDF plugin.
However, there is a slight issue:
- With only Markdown extensions, Mermaid diagrams are not rendered correctly when converted to PDF.
- Using kroki is the standard solution, but it requires sending models to a SaaS service.
In particular, I found the handling of information sent to kroki to be ambiguous, and I was concerned about performance when rendering a large number of models.
Therefore, I created my own MkDocs plugin that converts Mermaid models to SVG.
Features
- SVG Output: Generates Mermaid diagrams as high-quality SVGs.
- Automatic Conversion: Automatically detects and converts Mermaid code blocks.
- Flexible Configuration: Allows specification of Mermaid themes and various settings.
- Flexible Control: Allows faster previews by disabling SVG conversion while authoring documents.
Requirements
Node.js is required to be installed beforehand.
Mermaid CLI
# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli
# Install per project
npm install @mermaid-js/mermaid-cli
Puppeteer
# Install Puppeteer
npm install puppeteer
# Install the browser for Puppeteer (Required)
npx puppeteer browsers install chrome-headless-shell
Setup
Install the plugin via pip.
pip install mkdocs-mermaid-to-svg
Enable the plugin in mkdocs.yml (Recommended settings for PDF generation).
plugins:
- mermaid-to-svg:
image_id_enabled: true
image_id_prefix: mermaid-diagram
# Disable HTML labels for PDF compatibility
mermaid_config:
htmlLabels: false
flowchart:
htmlLabels: false
class:
htmlLabels: false
- to-pdf: # When using with PDF generation plugin
enabled_if_env: ENABLE_PDF_EXPORT
Note
Even ifmermaid_configis omitted, the plugin automatically generates a temporary configuration file withhtmlLabels(including those forflowchartandclass) disabled. Since the basic settings for PDF compatibility are always applied, only specifymermaid_configif you need custom Mermaid settings.
PDF Compatibility
When htmlLabels is enabled, Mermaid CLI generates SVGs containing <foreignObject> which include HTML. PDF generation tools cannot render these HTML elements correctly, which causes text to disappear.
- Affected Diagrams: Flowcharts, class diagrams, etc., that use HTML for labels.
- Unaffected Diagrams: Sequence diagrams are fine in PDFs as they use standard SVG text elements.
Configuration
You can customize the plugin behavior in mkdocs.yml. All settings are optional.
Conditional Activation
To enable the plugin only during PDF generation, use the same environment variable as the to-pdf plugin.
plugins:
- mermaid-to-svg:
enabled_if_env: "ENABLE_PDF_EXPORT" # Use the same env var as to-pdf
mermaid_config:
htmlLabels: false
flowchart:
htmlLabels: false
class:
htmlLabels: false
- to-pdf:
enabled_if_env: ENABLE_PDF_EXPORT
Example command:
ENABLE_PDF_EXPORT=1 mkdocs build
Advanced Options
plugins:
- mermaid-to-svg:
mmdc_path: "mmdc" # Path to Mermaid CLI
css_file: "custom-mermaid.css" # Custom CSS
puppeteer_config: "puppeteer.json" # Puppeteer config file
error_on_fail: false # Continue processing even if generation fails
log_level: "WARNING" # Currently overridden by mkdocs CLI flags (see below)
cleanup_generated_images: true # Remove generated images after build
image_id_enabled: true # Assign ID to generated <img>
image_id_prefix: "mermaid-diagram" # ID prefix (attr_list required)
Mermaid image IDs
Withimage_id_enabled: true, you can assign deterministic IDs (e.g.,mermaid-diagram-guide-1) to each generated image. This is useful for diagram-specific CSS styling or size adjustments in PDF output.
- If the Markdown
attr_listextension is not enabled, MkDocs will treat{#...}as a string.- You can change the prefix with
image_id_prefix. You can also specify individual IDs by adding{id: "custom-id"}to the code fence.
Configuration example:
markdown_extensions:
- attr_list
plugins:
- mermaid-to-svg:
image_id_enabled: true
image_id_prefix: "diagram"
Configuration Option List
| Option | Default | Description |
|---|---|---|
enabled_if_env |
None |
Environment variable name to enable the plugin. |
output_dir |
"assets/images" |
Directory to place the generated SVGs. |
theme |
"default" |
Mermaid theme (default, dark, forest, neutral). |
mmdc_path |
"mmdc" |
Path to the mmdc executable. |
cli_timeout |
90 |
Mermaid CLI timeout in seconds. Adjust for extremely small or heavy diagrams. |
mermaid_config |
None |
Dictionary for Mermaid configuration. |
css_file |
None |
Path to a custom CSS file. |
puppeteer_config |
None |
Path to a Puppeteer configuration file. |
error_on_fail |
true |
Whether to stop the build on generation errors. |
log_level |
auto |
Ignored in mkdocs.yml; fixed to DEBUG when running mkdocs build --verbose/-v, otherwise WARNING. |
cleanup_generated_images |
true |
Whether to delete generated images after the build. |
image_id_enabled |
false |
Assign {#id} to the generated image Markdown (requires attr_list). |
image_id_prefix |
"mermaid-diagram" |
ID prefix used when image_id_enabled is true. |
Logging Behavior
The log level is forced toDEBUGwhen runningmkdocs build --verboseor-v, andWARNINGotherwise. Values specified inmkdocs.ymlare currently ignored.
Execution Notes
-
mkdocs serveleaves Mermaid code blocks as they are and only performs conversion duringmkdocs build. -
enabled_if_envrequires an environment variable that "exists and is not an empty string." If unset or empty, it remains disabled. - If the specified
mmdc_pathis not available, it falls back tonpx mmdc. - If
puppeteer_configis omitted or does not exist, a temporary configuration for headless execution is automatically generated and cleaned up after use.
PDF Generation
This plugin is designed with PDF compatibility in mind.
Why SVG?
- Vector Format: Scales beautifully at any resolution.
- Text Retention: Allows text selection and search even in PDFs.
- No JavaScript Needed: Works even with PDF generation tools that have JavaScript disabled.
Usage Example
-
Write a Mermaid diagram in Markdown:
```mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2] ``` -
It is automatically converted to SVG during build:
<p><img alt="Mermaid Diagram" src="assets/images/diagram_123abc.svg" /></p> -
Even when exported to PDF, it appears as a smooth diagram with selectable text.
Discussion