# mkdocs-mermaid-to-svg
[![PyPI - Python Version][python-image]][pypi-link]
[![Linux Support][linux-image]](#requirements)
[![Windows Support][windows-image]](#requirements)
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.
- [Documentation](https://thankful-beach-0f331f600.1.azurestaticapps.net/)
## 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](https://nodejs.org/) to be installed beforehand.
### Mermaid CLI
```bash
# Install Mermaid CLI globally
npm install -g @mermaid-js/mermaid-cli
# Or install per project
npm install @mermaid-js/mermaid-cli
```
### Puppeteer
```bash
# Install Puppeteer
npm install puppeteer
# Install browser for Puppeteer (required)
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` (recommended configuration for PDF generation):
```yaml
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:
```yaml
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:
```bash
ENABLE_PDF_EXPORT=1 mkdocs build
```
### Advanced Options
```yaml
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
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
[linux-image]: https://img.shields.io/badge/Linux-supported-success?logo=linux&logoColor=white&labelColor=333333
[windows-image]: https://img.shields.io/badge/Windows-supported-success?logo=windows&logoColor=white&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/1e/bd/41ff56ebcf722154d6422f2f57a2ed6c852c9a9fbf54e860f832b53c3137/mkdocs_mermaid_to_svg-1.0.1.tar.gz",
"platform": null,
"description": "# mkdocs-mermaid-to-svg\n\n[![PyPI - Python Version][python-image]][pypi-link]\n[![Linux Support][linux-image]](#requirements)\n[![Windows Support][windows-image]](#requirements)\n\nAn MkDocs plugin to convert Mermaid charts to SVG images.\n\nThis 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.\n\n- [Documentation](https://thankful-beach-0f331f600.1.azurestaticapps.net/)\n\n## Features\n\n- **SVG output**: Generates high-quality SVG images from Mermaid diagrams\n- **PDF compatible**: SVG images work perfectly in PDF exports\n- **Automatic conversion**: Automatically detects and converts all Mermaid code blocks\n- **Configurable**: Supports Mermaid themes and custom configurations\n- **Environment control**: Can be conditionally enabled via environment variables\n\n## Requirements\n\nThis plugin requires [Node.js](https://nodejs.org/) to be installed beforehand.\n\n### Mermaid CLI\n\n```bash\n# Install Mermaid CLI globally\nnpm install -g @mermaid-js/mermaid-cli\n\n# Or install per project\nnpm install @mermaid-js/mermaid-cli\n```\n\n### Puppeteer\n\n```bash\n# Install Puppeteer\nnpm install puppeteer\n\n# Install browser for Puppeteer (required)\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` (recommended configuration for PDF generation):\n\n```yaml\nplugins:\n - mermaid-to-svg:\n # Disable HTML labels for PDF compatibility\n mermaid_config:\n htmlLabels: false\n flowchart:\n htmlLabels: false\n class:\n htmlLabels: false\n - to-pdf: # When used with PDF generation plugins\n enabled_if_env: ENABLE_PDF_EXPORT\n```\n\n### PDF Compatibility\n\nWhen `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.\n\n- **Affected diagrams**: Flowcharts, class diagrams, and other diagrams that use text labels\n- **Not affected**: Sequence diagrams use standard SVG text elements and work correctly in PDFs\n\n## Configuration\n\nYou can customize the plugin's behavior in `mkdocs.yml`. All options are optional:\n\n### Conditional Activation\n\nTo enable the plugin only during PDF generation, use the same environment variable as the to-pdf plugin:\n\n```yaml\nplugins:\n - mermaid-to-svg:\n enabled_if_env: \"ENABLE_PDF_EXPORT\" # Use same env var as to-pdf plugin\n mermaid_config:\n htmlLabels: false\n flowchart:\n htmlLabels: false\n class:\n htmlLabels: false\n - to-pdf:\n enabled_if_env: ENABLE_PDF_EXPORT\n```\n\nRun with:\n```bash\nENABLE_PDF_EXPORT=1 mkdocs build\n```\n\n### Advanced Options\n\n```yaml\nplugins:\n - mermaid-to-svg:\n mmdc_path: \"mmdc\" # Path to Mermaid CLI\n css_file: \"custom-mermaid.css\" # Custom CSS file\n puppeteer_config: \"puppeteer.json\" # Custom Puppeteer configuration\n error_on_fail: false # Continue on diagram generation errors\n log_level: \"INFO\" # Log level (DEBUG, INFO, WARNING, ERROR)\n cleanup_generated_images: true # Clean up generated images after build\n```\n\n## Configuration 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| `mmdc_path` | `\"mmdc\"` | Path to `mmdc` executable |\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| `error_on_fail` | `true` | Stop build on diagram generation errors |\n| `log_level` | `\"INFO\"` | Log level |\n| `cleanup_generated_images` | `true` | Clean up generated images after build |\n\n## PDF Generation\n\nThis plugin is designed with PDF generation compatibility in mind:\n\n### Why SVG?\n\n- **Vector format**: SVG images scale beautifully at any resolution\n- **Text preservation**: SVG text remains selectable and searchable in PDFs\n- **No JS required**: Works with PDF generation tools that don't support JavaScript\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[linux-image]: https://img.shields.io/badge/Linux-supported-success?logo=linux&logoColor=white&labelColor=333333\n[windows-image]: https://img.shields.io/badge/Windows-supported-success?logo=windows&logoColor=white&labelColor=333333\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin to preprocess Mermaid diagrams into static SVG images",
"version": "1.0.1",
"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": "3aaccb6fab1f4aba2e13785da8f4e10f42b4edf1f9224781fcfdd9e57ee07329",
"md5": "0f5c5f1c6465db5603b367d60d7a12ca",
"sha256": "1de59f4968c26bce3ef93fcf42be9cddcbf9ecc7c3dc473af16d6f5e13137412"
},
"downloads": -1,
"filename": "mkdocs_mermaid_to_svg-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f5c5f1c6465db5603b367d60d7a12ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 23808,
"upload_time": "2025-07-17T11:25:02",
"upload_time_iso_8601": "2025-07-17T11:25:02.335425Z",
"url": "https://files.pythonhosted.org/packages/3a/ac/cb6fab1f4aba2e13785da8f4e10f42b4edf1f9224781fcfdd9e57ee07329/mkdocs_mermaid_to_svg-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1ebd41ff56ebcf722154d6422f2f57a2ed6c852c9a9fbf54e860f832b53c3137",
"md5": "7037d04cde0143b9af84770b0be3d0cd",
"sha256": "299780d586048f2ad77e44e286089b2c11e09ea731e6a3611c3b895e94249c94"
},
"downloads": -1,
"filename": "mkdocs_mermaid_to_svg-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7037d04cde0143b9af84770b0be3d0cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 265733,
"upload_time": "2025-07-17T11:25:03",
"upload_time_iso_8601": "2025-07-17T11:25:03.581902Z",
"url": "https://files.pythonhosted.org/packages/1e/bd/41ff56ebcf722154d6422f2f57a2ed6c852c9a9fbf54e860f832b53c3137/mkdocs_mermaid_to_svg-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 11:25:03",
"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
