mkdocs-svg-to-png¶

An MkDocs plugin that converts SVG code blocks and files to PNG images using Playwright during the build process. This plugin is specifically designed to ensure proper SVG rendering in PDF output and offline viewing scenarios.

Primary use case: Works seamlessly with mkdocs-mermaid-to-svg to create a complete local pipeline for Mermaid diagrams → SVG → PNG → PDF generation without external services, ensuring confidentiality for sensitive documentation.

Features¶

SVG to PNG Conversion: Automatically converts SVG code blocks and file references to high-quality PNG images
Playwright-based Rendering: Uses browser-grade rendering for accurate SVG-to-PNG conversion
PDF Optimization: Ensures consistent rendering in PDF output generated by mkdocs-to-pdf
Conditional Activation: Enable only during PDF builds using environment variables
Local Processing: No external services required - maintains document confidentiality
Caching Support: Avoids re-rendering unchanged SVG content
Flexible Configuration: Comprehensive options for output control and error handling

Requirements¶

This plugin requires Python 3.9+ and automatically installs the following dependencies:

MkDocs (>=1.4.0) - Documentation site generator
MkDocs Material (>=8.0.0) - Material theme for MkDocs
Playwright (>=1.40.0) - Browser automation for SVG to PNG conversion

Installation¶

Install the plugin using pip:

pip install mkdocs-svg-to-png
python -m playwright install

If you're using uv (recommended for development):

uv add mkdocs-svg-to-png
uv run python -m playwright install

Important: The python -m playwright install command is required to download the browser binaries that Playwright needs for rendering SVG content. Without this step, the plugin will fail to convert SVG files.

Quick Start¶

Add the plugin to your mkdocs.yml:

plugins:
  - search
  - svg-to-png:
      enabled_if_env: ENABLE_PDF_EXPORT

For a complete Mermaid → SVG → PNG → PDF pipeline:

plugins:
  - search
  - mermaid-to-svg:
      enabled_if_env: ENABLE_PDF_EXPORT
  - svg-to-png:
      enabled_if_env: ENABLE_PDF_EXPORT
  - to-pdf:
      enabled_if_env: ENABLE_PDF_EXPORT

This creates a complete pipeline: 1. mermaid-to-svg converts Mermaid diagrams to SVG 2. svg-to-png converts SVG to high-quality PNG images 3. to-pdf generates PDF with properly rendered diagrams

Usage¶

Development vs Production Builds¶

For optimal workflow, use conditional activation:

# Development: Fast preview without image conversion
mkdocs serve

# Production: Build with image conversion and PDF generation
ENABLE_PDF_EXPORT=1 mkdocs build

This approach ensures fast iteration during development while maintaining high-quality output for production builds.

SVG Code Block Example¶

\`\`\`svg
<svg width="100" height="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red" />
</svg>
\`\`\`

The plugin will automatically convert this to a PNG image and replace the code block with an <img> tag.

SVG File References¶

The plugin also converts SVG file references:

![Diagram](path/to/diagram.svg)

Configuration Options¶

All configuration options with their defaults:

plugins:
  - svg-to-png:
      enabled_if_env: null              # Environment variable for conditional activation
      output_dir: "assets/images"       # Directory for generated PNG images
      preserve_original: false          # Keep original SVG alongside PNG
      error_on_fail: false             # Stop build on conversion failure
      log_level: "INFO"                # Logging level (DEBUG/INFO/WARNING/ERROR)
      cleanup_generated_images: false   # Remove generated images after build

Configuration Details¶

enabled_if_env (default: null)
Environment variable name to conditionally enable the plugin
Plugin activates only when the variable is set and non-empty
The check happens once at MkDocs startup and is not re-evaluated mid-run
If null, plugin is always enabled
output_dir (default: "assets/images")
Directory where generated PNG images are saved
Relative to your docs directory
preserve_original (default: false)
If true, keeps original SVG content alongside generated PNG
Useful for debugging or dual-format support
error_on_fail (default: false)
If true, stops build when SVG conversion fails
If false, logs errors and continues (skips failed conversions)
log_level (default: "INFO")
Controls plugin logging verbosity
Options: "DEBUG", "INFO", "WARNING", "ERROR"
cleanup_generated_images (default: false)
If true, removes generated PNG images after build completes
Useful for CI/CD environments to avoid accumulating artifacts

Use Cases¶

PDF Generation Pipeline¶

This plugin is particularly valuable when generating PDFs from MkDocs documentation:

Mermaid Diagrams: Use mkdocs-mermaid-to-svg to convert Mermaid code to SVG
SVG Conversion: This plugin converts SVG to PNG for reliable PDF rendering
PDF Output: Use mkdocs-to-pdf to generate final PDF with properly rendered images

Offline Documentation¶

Convert SVG graphics to PNG for environments where SVG support may be limited or inconsistent.

Corporate/Confidential Documents¶

Process diagrams and graphics locally without relying on external services, maintaining document confidentiality.

Error Handling¶

The plugin provides structured error handling:

Conversion Failures: Logged with detailed error messages
Missing Dependencies: Clear instructions for resolving setup issues
File System Errors: Graceful handling of permission and path issues

Set error_on_fail: true to stop builds on conversion failures, or false to log errors and continue.

Troubleshooting¶

Common Issues¶

"Playwright not installed" error
```
python -m playwright install
```
Permission denied errors
Check write permissions for output_dir
Ensure temp directory is writable
SVG parsing errors
Validate SVG syntax
Check for unsupported SVG features

Debug Logging¶

Enable detailed logging for troubleshooting:

plugins:
  - svg-to-png:
      log_level: "DEBUG"

Development¶

For development setup and contributing guidelines, see the project repository.

mkdocs-mermaid-to-svg - Converts Mermaid diagrams to SVG
mkdocs-to-pdf - Generates PDF from MkDocs sites

License¶

MIT License