How to Export Diagrams to PNG and SVG in Diagram Design

Diagram Design provides built-in slash commands that extract the embedded <svg> element for vector output or rasterize it via Playwright for high-resolution PNG assets.

The cathrynlavery/diagram-design repository stores every diagram as a self-contained HTML file. To convert these web-based diagrams into portable image formats, the skill implements a robust export pipeline defined in skills/diagram-design/references/export.md and exposed through the commands/export-diagram.md specification.

Understanding the Export Architecture

Diagram Design persists diagrams as standalone HTML documents containing embedded SVG markup. When you initiate an export, the system loads the target file, locates the first <svg> node, and processes it according to your requested format.

For SVG export, the tool injects required Google Fonts directly into the markup, producing a standalone vector file that renders correctly without external dependencies. For PNG export, the system launches a Playwright-controlled Chromium instance, renders the SVG at your specified device-scale factor, and captures a raster bitmap.

This architecture ensures vector fidelity for print and scaling workflows while providing pixel-perfect raster assets for presentations and web previews.

Available Export Commands

The skill exposes three distinct slash commands that invoke the same underlying export logic with different default behaviors.

Standard Export

Run /export-diagram to generate both formats simultaneously.

/export-diagram path/to/diagram.html

This writes diagram.svg and diagram.png (at 2× scale) adjacent to the source file.

Format-Specific Exports

Use flags to isolate specific output types:

# Vector only

/export-diagram path/to/diagram.html --svg-only

# Raster only at 3× resolution

/export-diagram path/to/diagram.html --png-only --scale=3

Natural Language Interface

You can also invoke exports conversationally:

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG with scale 2."

The skill parses these requests and applies sensible defaults before executing the export procedure documented in the reference files.

Step-by-Step Export Workflows

Exporting to SVG Format

SVG exports require no external browser dependencies. The workflow implemented in skills/diagram-design/references/export.md executes as follows:

1. Parses the HTML file to extract the first <svg> element
2. Injects Google Fonts CSS into the SVG <defs> section to ensure typography renders correctly offline
3. Writes the modified markup to [filename].svg or your specified --output path

The resulting file is a truly standalone vector graphic suitable for editing in Illustrator, Figma, or Inkscape.

Exporting to PNG Format

PNG generation requires Playwright installation:

pip install playwright
playwright install chromium

The rasterization process follows these steps:

1. Launches headless Chromium via Playwright
2. Sets viewport to the SVG's native dimensions multiplied by the scale factor (default 2×, supports 1×, 2×, or 3×)
3. Renders the SVG with full font support
4. Captures screenshot and encodes as PNG

Higher scale factors produce sharper images for retina displays and print materials at 300+ DPI.

Command Flags and Options

The commands/export-diagram.md specification defines the following flags:

• --svg-only – Skip PNG generation, output vector file only
• --png-only – Skip SVG generation, output raster file only
• --scale={1,2,3} – Set PNG resolution multiplier (default: 2)
• --output=path/basename – Custom output path and base filename without extension

When both format flags are omitted, the command produces both files. When --output is specified, the system appends .svg or .png to your provided basename.

Edge Cases and Validation

The export logic includes strict guards defined in the command specification and validated at runtime via skills/diagram-design/scripts/self_check.py:

• Missing source file – Command refuses if no HTML path is supplied
• Gallery exclusion – Cannot export assets/index.html because it contains multiple diagram canvases
• Missing SVG element – Fails gracefully if the HTML lacks an <svg> node
• Playwright availability – PNG requests trigger a dependency check; if Playwright is absent, the system displays installation instructions rather than crashing
• Scale validation – Rejects scale factors outside 1, 2, or 3

These safeguards ensure that CI pipelines using scripts/verify-export.py receive deterministic results and clear error messages when constraints are violated.

Summary

• Diagram Design stores diagrams as HTML files containing SVG markup in the cathrynlavery/diagram-design repository
• SVG export extracts and font-injects the vector element for standalone use without Playwright
• PNG export requires Playwright and Chromium to rasterize the diagram at scale factors of 1×, 2×, or 3×
• Use /export-diagram with --svg-only, --png-only, --scale, and --output flags to control output formats and destinations
• The system validates inputs against edge cases including missing files, gallery directories, and unsupported scale values

Frequently Asked Questions

What is the default PNG resolution?

PNG exports default to 2× scale, producing images with twice the pixel density of the diagram's native SVG dimensions. You can override this with --scale=1 for standard resolution or --scale=3 for ultra-high DPI requirements.

Why does PNG export require Playwright while SVG does not?

SVG files are pure markup extracted directly from the HTML source. PNG files require rasterization, which necessitates a browser engine to calculate CSS, execute font loading, and render the final pixel buffer. The skills/diagram-design/references/export.md implementation uses Playwright to automate Chromium for this headless rendering task.

Can I export multiple diagrams at once?

No. The commands/export-diagram.md specification explicitly blocks the gallery file (assets/index.html) and requires single HTML inputs. This design ensures accurate file size reporting and prevents ambiguity in output naming. Batch processing requires scripting multiple individual export commands.

What happens if the HTML file contains no SVG element?

The command validates the DOM structure before processing and terminates with an error message if no <svg> node is detected. This validation occurs early in the workflow defined in the export reference file, preventing empty or corrupted output files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}