mkdocs-svg-to-png 1.0.0

MkDocs plugin to convert SVG files to PNG images during build

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
  • 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:

1. Mermaid Diagrams: Use mkdocs-mermaid-to-svg to convert Mermaid code to SVG
2. SVG Conversion: This plugin converts SVG to PNG for reliable PDF rendering
3. 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

1. "Playwright not installed" error

   python -m playwright install
   

2. Permission denied errors

   • Check write permissions for output_dir
   • Ensure temp directory is writable

3. 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.

Related Projects

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

License

MIT License