mkdocs-mermaid-to-svg¶

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
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:
      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)

Mermaid image IDs Set image_id_enabled: true to 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_list extension, 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 (default, dark, forest, neutral)
`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

Log level behaviour The plugin currently overrides log_level based on the MkDocs CLI flags: mkdocs build --verbose or -v forces DEBUG, and omitting them forces WARNING. Values specified in mkdocs.yml are ignored for now.

Runtime Notes¶

mkdocs serve leaves Mermaid fences untouched; conversion runs during mkdocs build.
enabled_if_env must be set to a non-empty environment variable to activate the plugin; missing or empty values keep it disabled.
If the configured mmdc_path is not available, the plugin falls back to npx mmdc.
When puppeteer_config is omitted or the file is missing, a temporary headless-friendly config is generated and cleaned up after use.

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.