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

> Easily export diagrams from Diagram-Design as PNG or SVG using the export-diagram command. Control format, scale, and destination for your vector and raster files.

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

---

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

```bash

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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/diagram.html) becomes `diagram.svg` and/or `diagram.png`. To redirect or rename, use `--output`:

```bash
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)](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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html)?

The [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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.