How to Export Diagrams from Diagram-Design as PNG or SVG

Use the export-diagram command to convert any diagram HTML file into both vector SVG and raster PNG files, with optional flags to control output format, scale, and destination.

The cathrynlavery/diagram-design repository treats each diagram as a standalone HTML file containing an embedded <svg> element. The export-diagram command orchestrates the conversion workflow defined in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), handling validation, rendering via Playwright, and file output.

How the Export Command Works

Input Validation and SVG Detection

The command begins by ensuring it has a valid target. If you omit the file path, the CLI prompts you to provide one. If you accidentally target the gallery file at assets/index.html, the command refuses and directs you to select a specific diagram file instead.

Once a path is accepted, the command scans the HTML for an <svg> block. Missing SVG content triggers an immediate exit with a descriptive error—no silent failures.

Output Format Selection

By default, export-diagram produces both SVG and PNG files. Two mutually exclusive flags override this behavior:

• --svg-only — Skip Playwright entirely and generate only the vector file
• --png-only — Skip SVG creation and render only the raster image

# Default: both formats

diagram-design export-diagram diagram.html

# SVG only, no Playwright dependency

diagram-design export-diagram diagram.html --svg-only

# PNG only, useful for quick previews

diagram-design export-diagram diagram.html --png-only

PNG Rendering with Playwright

When PNG output is requested, the command delegates to Playwright. It loads the SVG onto a virtual page and captures a screenshot. The device scale factor defaults to 2 (high-DPI) for crisp output on retina displays, but you can override this:

# 1× scale (standard resolution)

diagram-design export-diagram diagram.html --scale=1

# 3× scale (maximum fidelity)

diagram-design export-diagram diagram.html --scale=3

If Playwright is not installed, the command aborts and prints the exact installation instructions from the reference guide. It never auto-installs dependencies—this design choice keeps the tool predictable and avoids side effects.

File Naming and Custom Output Paths

Output filenames derive automatically from the source: diagram.html becomes diagram.svg and/or diagram.png. To redirect or rename, use --output:

diagram-design export-diagram diagram.html --output=out/my-diagram

# Creates: out/my-diagram.svg, out/my-diagram.png

The command appends the correct extension—you supply the base path.

Completion Reporting

After writing files, the command echoes full paths and file sizes. This transparency helps you locate assets immediately and verify export success.

Complete CLI Reference

Flag	Values	Effect
(none)	—	Export both SVG and PNG
--svg-only	—	Skip PNG, output SVG only
--png-only	—	Skip SVG, output PNG only
--scale	1, 2 (default), 3	Device scale factor for PNG
--output	Any valid path	Base name/location for outputs

Key Source Files

Understanding the implementation helps debug edge cases or extend functionality:

• [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) — Command definition, flag parsing, validation logic, and orchestration flow
• [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) — Authoritative workflow documentation, Playwright configuration, and troubleshooting guidance

Summary

• Primary command: diagram-design export-diagram <file.html>
• Default behavior: Generates both SVG (direct extraction) and PNG (Playwright-rendered)
• Format control: Use --svg-only or --png-only to isolate outputs
• Resolution control: --scale adjusts PNG device scale factor (1–3)
• Destination control: --output sets custom base paths with automatic extension handling
• Dependency handling: Playwright is required for PNG; missing installs trigger guided instructions, never automatic installation

Frequently Asked Questions

Can I export diagrams without installing Playwright?

Yes. Use the --svg-only flag to extract the SVG directly from the HTML without any browser automation. This bypasses the Playwright dependency entirely.

Why does the command refuse to export assets/index.html?

The assets/index.html file is the gallery index, not a diagram. The command protects against bulk-export accidents by requiring a specific diagram file. Select an individual .html file from your diagrams directory instead.

How do I get higher resolution PNG exports?

Increase the device scale factor with --scale=3. This renders the SVG at 3× resolution before capturing, producing sharper images for presentations or print materials.

What happens if the HTML file has no SVG element?

The command exits immediately with a descriptive error message. This validation prevents empty or malformed outputs and alerts you to diagram structure problems.

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