# mkdocs-mermaid-to-svg
[![PyPI - Python Version][python-image]][pypi-link]
An MkDocs plugin to convert Mermaid charts to SVG images.
This plugin finds Mermaid code blocks and replaces them with SVG images. This is especially useful for formats that don't support JavaScript, like PDF generation.
- [Documents](https://thankful-beach-0f331f600.1.azurestaticapps.net/)
## Features
- **SVG-only output**: Generates high-quality SVG images from Mermaid diagrams
- **PDF compatible**: SVG images work perfectly in PDF exports
- **Automatic conversion**: Finds and converts all Mermaid code blocks
- **Configurable**: Supports Mermaid themes and custom configurations
- **Environment-aware**: Can be conditionally enabled via environment variables
## Requirements
This plugin requires a Mermaid execution engine. Please install one of the following:
- [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)
- [Node.js](https://nodejs.org/) with [Puppeteer](https://pptr.dev/)
For Mermaid CLI to work properly, you also need to install a browser for Puppeteer:
```bash
npx puppeteer browsers install chrome-headless-shell
```
## Setup
Install the plugin using pip:
```bash
pip install mkdocs-mermaid-to-svg
```
Activate the plugin in `mkdocs.yml`:
```yaml
plugins:
- search
- mermaid-to-svg
```
> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.
## Configuration
You can customize the plugin's behavior in `mkdocs.yml`. All options are optional:
### Basic Configuration
```yaml
plugins:
- mermaid-to-svg:
output_dir: "assets/images" # Where to store generated SVG files
theme: "default" # Mermaid theme (default, dark, forest, neutral)
background_color: "white" # Background color for diagrams
width: 800 # Image width in pixels
height: 600 # Image height in pixels
scale: 1.0 # Scale factor for the diagram
```
### PDF-Compatible Configuration
For PDF generation, use this configuration to ensure text displays correctly:
```yaml
plugins:
- mermaid-to-svg:
mermaid_config:
# Essential for PDF compatibility
htmlLabels: false
flowchart:
htmlLabels: false
class:
htmlLabels: false
theme: "default"
```
### Conditional Activation
Enable the plugin only when generating PDFs:
```yaml
plugins:
- mermaid-to-svg:
enabled_if_env: "ENABLE_MERMAID_SVG" # Only enable if this env var is set
```
Then run:
```bash
ENABLE_MERMAID_SVG=1 mkdocs build
```
### Advanced Options
```yaml
plugins:
- mermaid-to-svg:
mmdc_path: "/path/to/mmdc" # Custom path to Mermaid CLI
temp_dir: "/tmp/mermaid" # Custom temporary directory
css_file: "custom-mermaid.css" # Custom CSS file
puppeteer_config: "puppeteer.json" # Custom Puppeteer configuration
preserve_original: true # Keep original Mermaid code in output
error_on_fail: false # Continue on diagram generation errors
log_level: "INFO" # Logging level (DEBUG, INFO, WARNING, ERROR)
cleanup_generated_images: false # Clean up generated images after build
```
## Available 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) |
| `background_color` | `"white"` | Background color for diagrams |
| `width` | `800` | Image width in pixels |
| `height` | `600` | Image height in pixels |
| `scale` | `1.0` | Scale factor for the diagram |
| `mmdc_path` | `None` | Path to `mmdc` executable (auto-detected if not set) |
| `mermaid_config` | `None` | Mermaid configuration dictionary |
| `css_file` | `None` | Path to custom CSS file |
| `puppeteer_config` | `None` | Path to Puppeteer configuration file |
| `temp_dir` | `None` | Custom temporary directory |
| `preserve_original` | `false` | Keep original Mermaid code in output |
| `error_on_fail` | `false` | Stop build on diagram generation errors |
| `log_level` | `"INFO"` | Logging level |
| `cleanup_generated_images` | `false` | Clean up generated images after build |
## PDF Generation
This plugin is specifically designed for PDF generation compatibility:
### Why SVG?
- **Vector graphics**: SVG images scale perfectly at any resolution
- **Text preservation**: SVG text remains selectable and searchable in PDFs
- **No JavaScript**: Works in PDF generators that don't support JavaScript
### PDF-Specific Issues and Solutions
1. **HTML Labels Problem**: Mermaid CLI generates SVG files with `<foreignObject>` elements containing HTML when `htmlLabels` is enabled. PDF generation tools cannot properly render these HTML elements, causing text to disappear.
**Solution**: Set `htmlLabels: false` in your `mermaid_config`:
```yaml
plugins:
- mermaid-to-svg:
mermaid_config:
htmlLabels: false
flowchart:
htmlLabels: false
class:
htmlLabels: false
```
2. **Affected Diagram Types**: Flowcharts, class diagrams, and other diagrams that use text labels.
3. **Not Affected**: Sequence diagrams already use standard SVG text elements and work correctly in PDFs.
## Usage Example
1. Write Mermaid diagrams in your Markdown:
````markdown
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
```
````
2. The plugin automatically converts them to SVG images during build:
```html
<p><img alt="Mermaid Diagram" src="assets/images/diagram_123abc.svg" /></p>
```
3. Your PDF exports will display crisp, scalable diagrams with selectable text.
[pypi-link]: https://pypi.org/project/mkdocs-mermaid-to-svg/
[python-image]: https://img.shields.io/pypi/pyversions/mkdocs-mermaid-to-svg?logo=python&logoColor=aaaaaa&labelColor=333333
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-mermaid-to-svg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "diagram, mermaid, mkdocs, preprocessing, static-generation, svg",
"author": "nuitsjp",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a8/18/dad35392c6df393ea1beb0dec679472abb644857e4aca59492ca75338a5e/mkdocs_mermaid_to_svg-1.0.0.tar.gz",
"platform": null,
"description": "# mkdocs-mermaid-to-svg\n\n[![PyPI - Python Version][python-image]][pypi-link]\n\nAn MkDocs plugin to convert Mermaid charts to SVG images.\n\nThis plugin finds Mermaid code blocks and replaces them with SVG images. This is especially useful for formats that don't support JavaScript, like PDF generation.\n\n- [Documents](https://thankful-beach-0f331f600.1.azurestaticapps.net/)\n\n## Features\n\n- **SVG-only output**: Generates high-quality SVG images from Mermaid diagrams\n- **PDF compatible**: SVG images work perfectly in PDF exports\n- **Automatic conversion**: Finds and converts all Mermaid code blocks\n- **Configurable**: Supports Mermaid themes and custom configurations\n- **Environment-aware**: Can be conditionally enabled via environment variables\n\n## Requirements\n\nThis plugin requires a Mermaid execution engine. Please install one of the following:\n\n- [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)\n- [Node.js](https://nodejs.org/) with [Puppeteer](https://pptr.dev/)\n\nFor Mermaid CLI to work properly, you also need to install a browser for Puppeteer:\n\n```bash\nnpx puppeteer browsers install chrome-headless-shell\n```\n\n## Setup\n\nInstall the plugin using pip:\n\n```bash\npip install mkdocs-mermaid-to-svg\n```\n\nActivate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n - search\n - mermaid-to-svg\n```\n\n> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\n## Configuration\n\nYou can customize the plugin's behavior in `mkdocs.yml`. All options are optional:\n\n### Basic Configuration\n\n```yaml\nplugins:\n - mermaid-to-svg:\n output_dir: \"assets/images\" # Where to store generated SVG files\n theme: \"default\" # Mermaid theme (default, dark, forest, neutral)\n background_color: \"white\" # Background color for diagrams\n width: 800 # Image width in pixels\n height: 600 # Image height in pixels\n scale: 1.0 # Scale factor for the diagram\n```\n\n### PDF-Compatible Configuration\n\nFor PDF generation, use this configuration to ensure text displays correctly:\n\n```yaml\nplugins:\n - mermaid-to-svg:\n mermaid_config:\n # Essential for PDF compatibility\n htmlLabels: false\n flowchart:\n htmlLabels: false\n class:\n htmlLabels: false\n theme: \"default\"\n```\n\n### Conditional Activation\n\nEnable the plugin only when generating PDFs:\n\n```yaml\nplugins:\n - mermaid-to-svg:\n enabled_if_env: \"ENABLE_MERMAID_SVG\" # Only enable if this env var is set\n```\n\nThen run:\n```bash\nENABLE_MERMAID_SVG=1 mkdocs build\n```\n\n### Advanced Options\n\n```yaml\nplugins:\n - mermaid-to-svg:\n mmdc_path: \"/path/to/mmdc\" # Custom path to Mermaid CLI\n temp_dir: \"/tmp/mermaid\" # Custom temporary directory\n css_file: \"custom-mermaid.css\" # Custom CSS file\n puppeteer_config: \"puppeteer.json\" # Custom Puppeteer configuration\n preserve_original: true # Keep original Mermaid code in output\n error_on_fail: false # Continue on diagram generation errors\n log_level: \"INFO\" # Logging level (DEBUG, INFO, WARNING, ERROR)\n cleanup_generated_images: false # Clean up generated images after build\n```\n\n## Available Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `enabled_if_env` | `None` | Environment variable name to conditionally enable plugin |\n| `output_dir` | `\"assets/images\"` | Directory to store generated SVG files |\n| `theme` | `\"default\"` | Mermaid theme (default, dark, forest, neutral) |\n| `background_color` | `\"white\"` | Background color for diagrams |\n| `width` | `800` | Image width in pixels |\n| `height` | `600` | Image height in pixels |\n| `scale` | `1.0` | Scale factor for the diagram |\n| `mmdc_path` | `None` | Path to `mmdc` executable (auto-detected if not set) |\n| `mermaid_config` | `None` | Mermaid configuration dictionary |\n| `css_file` | `None` | Path to custom CSS file |\n| `puppeteer_config` | `None` | Path to Puppeteer configuration file |\n| `temp_dir` | `None` | Custom temporary directory |\n| `preserve_original` | `false` | Keep original Mermaid code in output |\n| `error_on_fail` | `false` | Stop build on diagram generation errors |\n| `log_level` | `\"INFO\"` | Logging level |\n| `cleanup_generated_images` | `false` | Clean up generated images after build |\n\n## PDF Generation\n\nThis plugin is specifically designed for PDF generation compatibility:\n\n### Why SVG?\n\n- **Vector graphics**: SVG images scale perfectly at any resolution\n- **Text preservation**: SVG text remains selectable and searchable in PDFs\n- **No JavaScript**: Works in PDF generators that don't support JavaScript\n\n### PDF-Specific Issues and Solutions\n\n1. **HTML Labels Problem**: Mermaid CLI generates SVG files with `<foreignObject>` elements containing HTML when `htmlLabels` is enabled. PDF generation tools cannot properly render these HTML elements, causing text to disappear.\n\n **Solution**: Set `htmlLabels: false` in your `mermaid_config`:\n ```yaml\n plugins:\n - mermaid-to-svg:\n mermaid_config:\n htmlLabels: false\n flowchart:\n htmlLabels: false\n class:\n htmlLabels: false\n ```\n\n2. **Affected Diagram Types**: Flowcharts, class diagrams, and other diagrams that use text labels.\n\n3. **Not Affected**: Sequence diagrams already use standard SVG text elements and work correctly in PDFs.\n\n## Usage Example\n\n1. Write Mermaid diagrams in your Markdown:\n\n ````markdown\n ```mermaid\n graph TD\n A[Start] --> B{Decision}\n B -->|Yes| C[Action 1]\n B -->|No| D[Action 2]\n ```\n ````\n\n2. The plugin automatically converts them to SVG images during build:\n\n ```html\n <p><img alt=\"Mermaid Diagram\" src=\"assets/images/diagram_123abc.svg\" /></p>\n ```\n\n3. Your PDF exports will display crisp, scalable diagrams with selectable text.\n\n[pypi-link]: https://pypi.org/project/mkdocs-mermaid-to-svg/\n[python-image]: https://img.shields.io/pypi/pyversions/mkdocs-mermaid-to-svg?logo=python&logoColor=aaaaaa&labelColor=333333\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin to preprocess Mermaid diagrams into static SVG images",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/nuitsjp/mkdocs-mermaid-to-svg/issues",
"Homepage": "https://github.com/nuitsjp/mkdocs-mermaid-to-svg",
"Source": "https://github.com/nuitsjp/mkdocs-mermaid-to-svg"
},
"split_keywords": [
"diagram",
" mermaid",
" mkdocs",
" preprocessing",
" static-generation",
" svg"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "26b0ca16d06a75b324f78672c2f28333efcc6b992a31fa95bfc83b2390ad58e2",
"md5": "f425c7326998f80f1d3f687ac93bf338",
"sha256": "543484a1de93356f671847a67b90e294e1493e0756b25013e8848ae3b481ee3e"
},
"downloads": -1,
"filename": "mkdocs_mermaid_to_svg-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f425c7326998f80f1d3f687ac93bf338",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24382,
"upload_time": "2025-07-12T22:28:25",
"upload_time_iso_8601": "2025-07-12T22:28:25.650938Z",
"url": "https://files.pythonhosted.org/packages/26/b0/ca16d06a75b324f78672c2f28333efcc6b992a31fa95bfc83b2390ad58e2/mkdocs_mermaid_to_svg-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a818dad35392c6df393ea1beb0dec679472abb644857e4aca59492ca75338a5e",
"md5": "c1a639d0a1122d06426ad8ba4cf8fdb1",
"sha256": "33283b55ac4860d83f8a022fa1e1e0c06f8e0f855adb7ae88abd982fd97303bd"
},
"downloads": -1,
"filename": "mkdocs_mermaid_to_svg-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c1a639d0a1122d06426ad8ba4cf8fdb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 261052,
"upload_time": "2025-07-12T22:28:26",
"upload_time_iso_8601": "2025-07-12T22:28:26.920975Z",
"url": "https://files.pythonhosted.org/packages/a8/18/dad35392c6df393ea1beb0dec679472abb644857e4aca59492ca75338a5e/mkdocs_mermaid_to_svg-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 22:28:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nuitsjp",
"github_project": "mkdocs-mermaid-to-svg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-mermaid-to-svg"
}
JSON
