Metadata-Version: 2.4
Name: mkdocs-svg-to-png
Version: 1.0.0
Summary: MkDocs plugin to convert SVG files to PNG images during build
Project-URL: Homepage, https://github.com/nuitsjp/mkdocs-svg-to-png
Project-URL: Bug Reports, https://github.com/nuitsjp/mkdocs-svg-to-png/issues
Project-URL: Source, https://github.com/nuitsjp/mkdocs-svg-to-png
Author: nuitsjp
License: MIT
License-File: LICENSE
Keywords: image-conversion,mkdocs,png,static-generation,svg
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Requires-Dist: mkdocs-material>=8.0.0
Requires-Dist: mkdocs>=1.4.0
Requires-Dist: playwright>=1.40.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
Requires-Dist: mkdocs-to-pdf>=0.10.1; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pip-audit>=2.6.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# mkdocs-svg-to-png

[![PyPI - Python Version][python-image]][pypi-link]

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](https://github.com/nuitsjp/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:

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

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

```bash
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`:

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

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

```yaml
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:

```bash
# 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

```markdown
\`\`\`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:

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

## Configuration Options

All configuration options with their defaults:

```yaml
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**
   ```bash
   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:

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

## Development

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

## Related Projects

- [mkdocs-mermaid-to-svg](https://github.com/nuitsjp/mkdocs-mermaid-to-svg) - Converts Mermaid diagrams to SVG
- [mkdocs-to-pdf](https://github.com/orzih/mkdocs-to-pdf) - Generates PDF from MkDocs sites

## License

MIT License

[pypi-link]: https://pypi.org/project/mkdocs-svg-to-png/
[python-image]: https://img.shields.io/pypi/pyversions/mkdocs-svg-to-png?logo=python&logoColor=aaaaaa&labelColor=333333
