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

> Easily export diagrams from Diagram-Design as PNG or SVG files. Learn how to use the export-diagram command to convert your HTML diagrams into popular image formats.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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)](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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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)](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)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) follows this reference document as the authoritative source.