How to Export Diagrams from Diagram-Design to PNG and SVG

The export-diagram command converts Diagram-Design's standalone HTML diagram files into both raster PNG (via Playwright) and vector SVG formats, placing the output files adjacent to the source by default.

The cathrynlavery/diagram-design repository stores diagrams as standalone HTML files containing embedded SVG elements. To export these diagrams to PNG and SVG formats for use in documentation or presentations, the project provides a dedicated CLI command that orchestrates the conversion process while enforcing validation rules defined in the reference implementation.

The Export Architecture

According to the command definition in commands/export-diagram.md, the export process builds upon the workflow documented in skills/diagram-design/references/export.md. Each diagram exists as an HTML file with an <svg> block at its core. The export-diagram command parses this structure to produce publication-ready assets without altering the source file.

Input Validation Requirements

The command first validates the input path. If you omit the file path, the CLI prompts you to provide one. If you attempt to export the gallery file at assets/index.html, the command refuses and requests a specific diagram file instead. Additionally, if the HTML lacks an <svg> element, the process exits immediately with an explanatory error message.

Export Modes and Rendering Options

By default, the command generates both formats simultaneously. You can control this behavior using specific flags.

Device Scale Factor for PNG Generation

When producing PNG files, the command uses Playwright to render the SVG on a virtual page and capture a screenshot. The default device scale factor is 2 (high-DPI), producing crisp images suitable for retina displays. Override this with the --scale flag accepting values of 1, 2, or 3.

Conditional PNG Generation

If Playwright is not installed in your environment, the command aborts and prints the exact installation instructions from the reference guide. The tool never auto-installs dependencies, ensuring you maintain control over your development environment.

Output File Handling

The command derives output filenames from the source file. For example, diagram.html produces diagram.svg and diagram.png in the same directory. Use the --output=<path> flag to specify a custom base path; the appropriate extensions append automatically. After writing, the command echoes the full paths and file sizes for verification.

Practical Export Examples

Here are the common usage patterns for the export-diagram command:

# Export both SVG and PNG (default behavior)

diagram-design export-diagram diagram.html

# Export only the SVG vector file (skip Playwright)

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

# Export only the PNG raster file (skip SVG creation)

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

# Generate high-resolution PNG with 3× scale factor

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

# Write outputs to custom directory and basename

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

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

Summary

• The export-diagram command in cathrynlavery/diagram-design converts HTML diagram files to PNG and SVG formats according to the logic defined in commands/export-diagram.md.
• Input validation prevents exporting the gallery file (assets/index.html) and requires a valid <svg> element in the source HTML.
• Playwright powers PNG generation with configurable scale factors (--scale=1|2|3), defaulting to 2× for high-DPI output.
• Use --svg-only or --png-only to generate specific formats, or omit flags for both.
• The --output flag redirects results to custom paths while preserving automatic extension handling.

Frequently Asked Questions

What is the default behavior when exporting diagrams from Diagram-Design?

By default, the export-diagram command produces both an SVG and a PNG version of your diagram. It places these files in the same directory as the source HTML file, using the same base filename with appropriate extensions.

How do I export only the SVG vector file without generating a PNG?

Append the --svg-only flag to your command. This skips the Playwright-based rendering step entirely, making the export faster when you only need the vector format.

Why does the export command reject my gallery file?

The command explicitly refuses to process assets/index.html because this file represents the gallery view rather than an individual diagram. The validation logic in commands/export-diagram.md requires you to specify a standalone diagram HTML file to ensure correct output naming and processing.

How do I install Playwright if the export command reports it as missing?

The command aborts and prints the exact installation instructions from skills/diagram-design/references/export.md rather than auto-installing. Follow the printed instructions, which typically involve running your package manager's install command for Playwright, then retry the export operation.

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