iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
📚

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 if mermaid_config is omitted, the plugin automatically generates a temporary configuration file with htmlLabels (including those for flowchart and class) disabled. Since the basic settings for PDF compatibility are always applied, only specify mermaid_config if 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
With image_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_list extension 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 to DEBUG when running mkdocs build --verbose or -v, and WARNING otherwise. Values specified in mkdocs.yml are currently ignored.

Execution Notes

  • mkdocs serve leaves Mermaid code blocks as they are and only performs conversion during mkdocs build.
  • enabled_if_env requires an environment variable that "exists and is not an empty string." If unset or empty, it remains disabled.
  • If the specified mmdc_path is not available, it falls back to npx mmdc.
  • If puppeteer_config is 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

  1. Write a Mermaid diagram in Markdown:

    ```mermaid
    graph TD
        A[Start] --> B{Decision}
        B -->|Yes| C[Action 1]
        B -->|No| D[Action 2]
    ```
    
  2. It is automatically converted to SVG during build:

    <p><img alt="Mermaid Diagram" src="assets/images/diagram_123abc.svg" /></p>
    
  3. Even when exported to PDF, it appears as a smooth diagram with selectable text.

Discussion