mkdocs-mermaid-to-svg
Japanese | English
An MkDocs plugin to convert Mermaid charts to SVG images.
This plugin detects Mermaid code blocks and replaces them with SVG images. This is especially useful for formats that don't support JavaScript, like PDF output.
Features
- SVG output: Generates high-quality SVG images from Mermaid diagrams
- Automatic conversion: Automatically detects and converts all Mermaid code blocks
- Configurable: Supports Mermaid themes and custom configurations
- beautiful-mermaid rendering: Fine-grained control over colors, fonts, spacing via beautiful-mermaid options
- Environment control: Can be conditionally enabled via environment variables
Requirements
This plugin requires Node.js to be installed beforehand.
Mermaid CLI
# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli
# Or install per project
npm install @mermaid-js/mermaid-cli
Puppeteer
# Install Puppeteer
npm install puppeteer
# Install browser for Puppeteer (required)
npx puppeteer browsers install chrome-headless-shell
Setup
Install the plugin using pip:
pip install mkdocs-mermaid-to-svg
Activate the plugin in mkdocs.yml (recommended configuration 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 used with PDF generation plugins
enabled_if_env: ENABLE_PDF_EXPORT
> **Note**
> If `mermaid_config` is omitted, the plugin automatically writes a temporary config that disables `htmlLabels` (including `flowchart` and `class` diagrams). The PDF-safe defaults are always applied; specify `mermaid_config` only when you need custom Mermaid settings.
PDF Compatibility
When htmlLabels is enabled, Mermaid CLI generates SVG files with <foreignObject> elements containing HTML. PDF generation tools cannot properly render these HTML elements, causing text to disappear.
- Affected diagrams: Flowcharts, class diagrams, and other diagrams that use text labels
- Not affected: Sequence diagrams use standard SVG text elements and work correctly in PDFs
Configuration
You can customize the plugin's behavior in mkdocs.yml. All options 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 same env var as to-pdf plugin
mermaid_config:
htmlLabels: false
flowchart:
htmlLabels: false
class:
htmlLabels: false
- to-pdf:
enabled_if_env: ENABLE_PDF_EXPORT
Run with:
ENABLE_PDF_EXPORT=1 mkdocs build
Advanced Options
plugins:
- mermaid-to-svg:
renderer: "auto" # auto: beautiful-mermaid優先, mmdc: 従来CLI固定
mmdc_path: "mmdc" # Path to Mermaid CLI
css_file: "custom-mermaid.css" # Custom CSS file
puppeteer_config: "puppeteer.json" # Custom Puppeteer configuration
error_on_fail: false # Continue on diagram generation errors
log_level: "WARNING" # Currently derived from mkdocs CLI flags (see note below)
cleanup_generated_images: true # Clean up generated images after build
image_id_enabled: true # Emit unique ids on rendered <img> tags
image_id_prefix: "mermaid-diagram" # Override id prefix (requires attr_list)
beautiful-mermaid Rendering Options
When using renderer: "auto", you can customize beautiful-mermaid rendering options globally in mkdocs.yml:
plugins:
- mermaid-to-svg:
renderer: "auto"
theme: "tokyo-night" # Named theme (tokyo-night, nord, etc.)
beautiful_mermaid_bg: "#1a1b26" # Background color
beautiful_mermaid_fg: "#c0caf5" # Foreground (text) color
beautiful_mermaid_line: "#565f89" # Line/edge color
beautiful_mermaid_accent: "#7aa2f7" # Accent color
beautiful_mermaid_font: "Inter" # Font family
beautiful_mermaid_padding: 20 # Diagram padding (px)
beautiful_mermaid_node_spacing: 80 # Node spacing (px)
beautiful_mermaid_transparent: true # Transparent background
Available options:
| Option | Type | Description |
|---|---|---|
beautiful_mermaid_bg |
str |
Background color |
beautiful_mermaid_fg |
str |
Foreground (text) color |
beautiful_mermaid_line |
str |
Line/edge color |
beautiful_mermaid_accent |
str |
Accent color |
beautiful_mermaid_muted |
str |
Muted color |
beautiful_mermaid_surface |
str |
Surface color |
beautiful_mermaid_border |
str |
Border color |
beautiful_mermaid_font |
str |
Font family |
beautiful_mermaid_padding |
int |
Diagram padding (px) |
beautiful_mermaid_node_spacing |
int |
Node spacing (px) |
beautiful_mermaid_layer_spacing |
int |
Layer spacing (px) |
beautiful_mermaid_transparent |
bool |
Transparent background |
Per-block overrides
You can override global options on individual code blocks using fence attributes:
```mermaid {bg: "#000000", font: "Fira Code"}
graph TD
A --> B
```
Block attributes take precedence over global mkdocs.yml settings. The theme attribute can also be overridden per block:
```mermaid {theme: "nord", accent: "#88c0d0"}
sequenceDiagram
Alice->>Bob: Hello
```
Note: beautiful-mermaid options only apply when
renderer: "auto"is set and the diagram type is supported (flowchart, sequence, class, ER, state). Unsupported types (pie, gantt, etc.) fall back to mmdc, where these options are ignored.
Mermaid image IDs Set
image_id_enabled: trueto add deterministic IDs (e.g.mermaid-diagram-guide-1) to every generated image. This allows per-diagram CSS targeting and PDF sizing tweaks.
- Enable the Markdown
attr_listextension, otherwise MkDocs will treat{#...}literally.- Override the prefix with
image_id_prefix. Custom IDs can also be supplied per code fence using{id: "custom-id"}attributes.
Example configuration:
markdown_extensions:
- attr_list
plugins:
- mermaid-to-svg:
image_id_enabled: true
image_id_prefix: "diagram"
Configuration Options
| Option | Default | Description |
|---|---|---|
enabled_if_env |
None |
Environment variable name to conditionally enable plugin |
output_dir |
"assets/images" |
Directory to store generated SVG files |
theme |
"default" |
Mermaid theme — mmdc built-ins (default, dark, forest, neutral) or beautiful-mermaid named themes (tokyo-night, nord, etc.) |
renderer |
"mmdc" |
auto=beautiful-mermaid優先(未導入/未対応時はmmdcへ), mmdc=従来CLI固定 |
mmdc_path |
"mmdc" |
Path to mmdc executable |
cli_timeout |
90 |
Timeout (seconds) for Mermaid CLI; adjust if your diagrams are very small/very heavy |
mermaid_config |
None |
Mermaid configuration dictionary |
css_file |
None |
Path to custom CSS file |
puppeteer_config |
None |
Path to Puppeteer configuration file |
error_on_fail |
true |
Stop build on diagram generation errors |
log_level |
auto |
Ignored in mkdocs.yml; resolves to DEBUG with mkdocs build --verbose/-v, otherwise WARNING |
cleanup_generated_images |
true |
Clean up generated images after build |
image_id_enabled |
false |
Attach {#id} suffixes to generated image Markdown (requires attr_list) |
image_id_prefix |
"mermaid-diagram" |
Prefix used for generated IDs when image_id_enabled is true |
beautiful_mermaid_* |
None |
beautiful-mermaid rendering options (see beautiful-mermaid Rendering Options) |
Log level behaviour The plugin currently overrides
log_levelbased on the MkDocs CLI flags:mkdocs build --verboseor-vforcesDEBUG, and omitting them forcesWARNING. Values specified inmkdocs.ymlare ignored for now.
Runtime Notes
mkdocs serveleaves Mermaid fences untouched; conversion runs duringmkdocs build.enabled_if_envmust be set to a non-empty environment variable to activate the plugin; missing or empty values keep it disabled.- If the configured
mmdc_pathis not available, the plugin falls back tonpx mmdc. - When
puppeteer_configis omitted or the file is missing, a temporary headless-friendly config is generated and cleaned up after use. renderer: autorequiresnodeandbeautiful-mermaidto be installed in the MkDocs project (e.g.npm install beautiful-mermaid).renderer: autofalls back to mmdc when the diagram type is unsupported (e.g. pie/gantt) or the renderer fails.
SVG Golden Tests
Golden SVG comparison tests run by default and can be skipped with:
SKIP_SVG_GOLDEN=1 uv run pytest tests/integration/test_svg_golden.py
To regenerate expected SVG files:
REGENERATE_SVG_GOLDENS=1 uv run pytest tests/integration/test_svg_golden.py
PDF Generation
This plugin is designed with PDF generation compatibility in mind:
Why SVG?
- Vector format: SVG images scale beautifully at any resolution
- Text preservation: SVG text remains selectable and searchable in PDFs
- No JS required: Works with PDF generation tools that don't support JavaScript
Usage Example
-
Write Mermaid diagrams in your Markdown:
```mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2] ```
-
The plugin automatically converts them to SVG images during build:
<p><img alt="Mermaid Diagram" src="assets/images/diagram_123abc.svg" /></p>
-
Your PDF exports will display crisp, scalable diagrams with selectable text.
Metadata
Release files for mkdocs-mermaid-to-svg 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mkdocs_mermaid_to_svg-1.3.0.tar.gz | 396.0 kB | Without provenance | Details for mkdocs_mermaid_to_svg-1.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mkdocs_mermaid_to_svg-1.3.0-py3-none-any.whl | Python 3 | none | any | Details for mkdocs_mermaid_to_svg-1.3.0-py3-none-any.whl |
Total release size: 441.7 kB
Release files / mkdocs_mermaid_to_svg-1.3.0.tar.gz
| Download URL | mkdocs_mermaid_to_svg-1.3.0.tar.gz |
|---|---|
| Size | 396.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4e9d22db99d89aa52862a1ec1d1500aa08a8b79c951fe966c8e2dcefcca21df
|
|
BLAKE2b-256 checksum How to use checksums |
ae27802263888deb5f738b128e98d137c493a9a997589e0d172089d7eabf0651
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / mkdocs_mermaid_to_svg-1.3.0-py3-none-any.whl
| Download URL | mkdocs_mermaid_to_svg-1.3.0-py3-none-any.whl |
|---|---|
| Size | 45.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c69e026ebbe9d992cd128071ca6b7049a309d5620612a26dc3e0e6956a47a0f9
|
|
BLAKE2b-256 checksum How to use checksums |
0809f13ed72bc39511ec88951c9188ba454786f59804a340a08e11301fe074de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for mkdocs-mermaid-to-svg 1.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.