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

Export diagrams from Diagram-Design using the export-diagram command, which converts standalone HTML diagram files into PNG (raster) and SVG (vector) formats via Playwright.

The cathrynlavery/diagram-design repository provides a purpose-built export workflow for converting diagram files into production-ready image assets. Every diagram in Diagram-Design is stored as a self-contained HTML file with an embedded <svg> element. The export-diagram command orchestrates the transformation of these files into distributable formats, following the authoritative specification in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md).

How the Export Command Works

The export process is defined in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). When invoked, the command performs six sequential operations:

1. Validates the input path — prompts if none provided; rejects the gallery file (assets/index.html) with a specific error
2. Verifies <svg> presence — exits early with an explanatory message if the HTML lacks SVG markup
3. Determines output formats — defaults to both SVG and PNG; respects --svg-only and --png-only flags
4. Renders PNG via Playwright — captures a screenshot with configurable device scale factor (default: 2)
5. Writes output files — derives names from source or uses --output base path
6. Reports results — displays full paths and file sizes upon completion

Exporting to Both PNG and SVG (Default Behavior)

Running the command without format flags produces both file types:

diagram-design export-diagram diagram.html

This creates diagram.svg and diagram.png in the same directory as the source file. The SVG is extracted directly from the HTML's <svg> block. The PNG is generated by rendering that SVG in a headless Playwright browser and capturing a screenshot.

Exporting SVG Only (Without Playwright)

Skip the PNG generation step entirely when you need only the vector file:

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

This avoids the Playwright dependency and executes faster, producing only diagram.svg.

Exporting PNG Only (Skip SVG Creation)

Generate raster output without the intermediate SVG file:

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

Useful when your workflow requires only bitmap assets.

Controlling PNG Resolution with Scale Factors

The default device scale factor of 2 produces high-DPI images suitable for retina displays. Override this with the --scale flag:

# Standard resolution (1×)

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

# Ultra-high resolution (3×)

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

Valid values are 1, 2, or 3. Higher values increase pixel density but also file size.

Specifying Custom Output Paths

Redirect exports to a different directory or base filename:

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

This writes out/my-diagram.svg and/or out/my-diagram.png depending on format flags. The command automatically appends the correct extension.

Handling Playwright Installation

If Playwright is not installed when PNG export is requested, the command does not auto-install. Instead, it prints the exact installation instructions from the reference guide and aborts. This behavior prevents unexpected environment modifications.

Install Playwright separately before running PNG exports:

npm install -g playwright

# or follow the instructions displayed by the command

Input Validation Rules

The command enforces strict validation as specified in the reference workflow:

• Missing path → interactive prompt for file selection
• Gallery file (assets/index.html) → rejection with message requesting a specific diagram file
• Missing <svg> element → early exit with diagnostic message

These guards prevent silent failures and ensure export attempts target valid diagram sources.

Summary

• Use export-diagram to convert Diagram-Design HTML files to PNG/SVG
• Default behavior generates both formats; use --svg-only or --png-only to limit output
• Control PNG resolution with --scale=1|2|3 (default: 2)
• Redirect outputs with --output=<base-path> for custom naming or directories
• Playwright is required for PNG generation but never auto-installed
• Follows canonical workflow defined in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)

Frequently Asked Questions

Can I export multiple diagrams at once?

The export-diagram command operates on single files. Batch processing requires shell scripting or sequential invocations. The command rejects the gallery file (assets/index.html) specifically to prevent accidental bulk exports of unsorted diagrams.

What happens if my HTML file contains no SVG?

The command detects missing <svg> elements and exits with an explanatory message before any file creation occurs. This validation step prevents empty or corrupted exports.

Does Diagram-Design support other export formats like PDF?

The current implementation in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) supports only PNG and SVG outputs. PDF export would require extending the Playwright screenshot configuration or post-processing the SVG through an external converter.

Where are the export settings and defaults defined?

All export behavior, flags, defaults, and edge-case handling are specified in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md). The command implementation in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) follows this reference document as the authoritative source.

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