How to Export Diagrams in SVG and PNG Formats in Diagram Design

Export diagrams as SVG and PNG files by running the /diagram-design:export-diagram command against any HTML diagram file, which extracts the embedded <svg> element for vector output and uses Playwright to rasterize the PNG with optional scaling.

The cathrynlavery/diagram-design repository stores diagrams as self-contained HTML files that embed scalable vector graphics. When you need production-ready assets for documentation, presentations, or web publishing, the export system generates clean, diagram-only artifacts without surrounding HTML wrappers.

Understanding the Export Architecture

Diagram Design treats each .html file as the canonical source. According to [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), the export command performs a deterministic transformation that respects accessibility metadata and visual fidelity. The system distinguishes between vector extraction (SVG) and rasterization (PNG), with the latter requiring a browser environment to resolve final visual states including loaded fonts and static motion frames.

Prerequisites for PNG Export

PNG generation requires Playwright with Chromium support. As documented in [skills/diagram-design/references/doctor.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/doctor.md), install the runtime before your first export:

pip install playwright && playwright install chromium

SVG exports require no external dependencies—the <svg> node is extracted directly from the DOM without browser rendering.

Basic Export Commands

The slash-command definition in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) supports several invocation patterns. By default, the command produces both formats in the source file's directory.

Export Both Formats

/diagram-design:export-diagram path/to/diagram.html

This creates path/to/diagram.svg and path/to/diagram.png using the base name of the HTML source.

Export SVG Only

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

The system extracts the <svg> element directly, preserving the <title> and <desc> elements for accessibility while omitting surrounding HTML wrappers.

Export PNG Only

/diagram-design:export-diagram path/to/diagram.html --png-only

Playwright renders the page, waits for document.fonts.ready, and captures the SVG's bounding box.

PNG Rasterization Details

When generating PNG files, the export routine loads the HTML in a headless browser to resolve the final visual state. The process documented in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) includes:

• Motion handling: Applies ?motion=static for motion-enabled diagrams to freeze animations
• Font resolution: Blocks until document.fonts.ready resolves, ensuring custom web fonts render correctly
• Transparent backgrounds: Uses omit_background=True for alpha-channel support
• Output naming: Saves to diagram.png in the same directory as the source HTML

Scaling PNG Output

Control rasterization resolution with the --scale factor:

/diagram-design:export-diagram path/to/diagram.html --png-only --scale=2

This generates a high-DPI PNG at double the native SVG resolution, suitable for retina displays or print media.

Generating the Registry Sidecar

For downstream tooling that requires block-level metadata, add the --registry flag to emit a .registry.json file:

/diagram-design:export-diagram path/to/diagram.html --registry

As specified in [skills/diagram-design/references/export-registry.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), this sidecar captures data-block-* attributes from the HTML. The command validates that data-block-id attributes exist before writing the registry; it refuses to emit empty metadata files and alerts the user accordingly. This operation does not require Playwright and executes independently of SVG or PNG generation.

Validation and Safety

The export system enforces strict user consent. It will not infer source paths or export empty diagrams. If you supply the --registry flag without block identifiers present in the HTML, the command aborts with a descriptive error rather than creating an empty JSON file.

Summary

• SVG exports extract the <svg> node directly from the DOM, preserving accessibility metadata (<title> and <desc>) and creating diagram-only artifacts without HTML wrappers.
• PNG exports require Playwright and Chromium to render fonts and static motion states, producing transparent-background images with configurable --scale factors.
• Output locations mirror the source HTML directory structure, using identical base filenames with appropriate extensions.
• Registry sidecars (.registry.json) capture block-level metadata but only when --registry is explicitly requested and valid data-block-id attributes exist.

Frequently Asked Questions

Does the export command work offline?

SVG exports function entirely offline since they parse the local HTML file directly. PNG exports require an internet connection during the first run to download Chromium via Playwright, but subsequent exports cache the browser binaries and work offline unless the diagram references remote fonts that must load during rendering.

Can I customize the background color of PNG exports?

The PNG export uses omit_background=True by default, producing transparent backgrounds. The repository documentation in [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) does not specify background color overrides; you would need to modify the SVG's own background properties or post-process the rasterized image.

What happens if the HTML file contains no diagram?

The export command validates content before writing files. It refuses to export empty diagrams and will exit with an error message rather than creating zero-byte or placeholder SVG/PNG files. Similarly, requesting --registry output on files without block identifiers results in a refusal to emit empty metadata.

Are animated diagrams supported?

Yes, but with limitations. The export process appends ?motion=static to the URL when rendering PNGs, freezing animations at their static state. The SVG export captures the current state of the DOM as-is, preserving any SMIL or CSS animations within the markup itself, though the PNG will always show the motionless frame.

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