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
PDF compatible: SVG images work perfectly in PDF exports
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:
      # 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

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: "INFO"                   # Log level (DEBUG, INFO, WARNING, ERROR)
      cleanup_generated_images: true      # Clean up generated images after build

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
`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`	`"INFO"`	Log level
`cleanup_generated_images`	`true`	Clean up generated images after build

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.