# Diagram-Design Export Options: Formats, Scaling, and Audience Settings

> Export diagrams from diagram-design to SVG or PNG. Control scale and audience settings to optimize resolution for any medium, from web to print. Learn more.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: api-reference
- Published: 2026-08-17

---

**Diagram-design exports diagrams to SVG, PNG, or both formats via the `export` command, supporting scale factors from 1 to 4 to optimize resolution for documentation, presentations, or print media.**

The cathrynlavery/diagram-design repository provides a flexible export pipeline defined in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) and [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), allowing users to generate production-ready assets tailored to specific viewing contexts.

## Supported Export Formats

Diagram-design supports three export modes controlled by CLI flags:

- **`--svg-only`** – Produces only the extracted SVG file without invoking Playwright, ideal for web embedding or further editing.
- **`--png-only`** – Generates only the PNG rasterization, suitable for platforms that require bitmap images.
- **Default (no flag)** – Emits both SVG and PNG side-by-side in a single operation.

The export command follows the syntax `diagram-design export <source.html>` with optional flags. By default, the tool derives output filenames from the input path, appending the appropriate extensions automatically.

## Size and Scale Configuration

Control output resolution using the **`--scale=N`** parameter, which sets the PNG device-scale factor applied to the SVG viewBox dimensions. According to [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), the final pixel dimensions equal **viewBox × scale**.

Accepted values range from **1 to 4**, including fractional decimals for exact sizing:

- Scale `1` renders at viewBox dimensions (compact)
- Scale `2` provides 2× resolution (default quality)
- Scale `3` delivers high-resolution for print media
- Fractional values (e.g., `1.25`) calculate precise widths like 1200px for OG cards

Values outside the 1–4 range are rejected to prevent quality degradation or excessive memory usage.

## Audience-Specific Export Presets

The reference documentation recommends specific scale factors based on target audience and distribution channel:

| Audience / Use Case | Recommended Scale | Result (1280×720 viewBox) |
|---------------------|-------------------|---------------------------|
| Documentation, README files, wikis | 2 | 2560×1440 |
| Slide decks (projected displays) | 2 | 2560×1440 |
| Print / PDF handouts | 3 | 3840×2160 |
| Inline thumbnails, email signatures | 1 | 1280×720 |

For custom dimensions, calculate the required scale by dividing target width by viewBox width. The tool accepts fractional scales to hit exact pixel requirements without manual resizing.

## CLI Usage Examples

Export both formats to the current directory:

```bash
diagram-design export diagram.html

```

Generate only an SVG for version control:

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

```

Create a high-resolution PNG for print media:

```bash
diagram-design export diagram.html --png-only --scale=3

```

Export to a custom output path (extensions appended automatically):

```bash
diagram-design export diagram.html --output=dist/final-diagram

```

Calculate fractional scale for exact 1200px width (assuming 960px viewBox):

```bash
diagram-design export diagram.html --png-only --scale=1.25

```

## Technical Constraints and Edge Cases

The export pipeline enforces specific guardrails documented in the command reference:

**Playwright Dependency** – PNG export requires Playwright installation. If missing, the tool halts with exact installation instructions:

```text
Playwright isn't installed. To enable PNG export, run:
pip install playwright
playwright install chromium

```

**Source Validation** – The tool refuses to export from [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) (gallery pages containing multiple SVGs) and prompts users to select a specific diagram file. Exports also fail with clear messaging when no `<svg>` element is detected.

**Font Warnings** – When system fonts referenced in the HTML are unavailable at runtime, the tool warns that PNG renderings may use fallback fonts and suggests fixing the source HTML before re-exporting.

**Full-Page Screenshots** – Requests for full-page captures (including UI cards) are declined; the command exports diagram-only content, directing users to browser-based screenshots for interface documentation.

## Summary

- **diagram-design** exports to **SVG**, **PNG**, or **both** via the `export` command defined in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md).
- Use **`--scale=N`** (1–4, fractional allowed) to control resolution based on **viewBox × scale** calculations.
- Target **scale 2** for documentation and slides, **scale 3** for print, and **scale 1** for thumbnails.
- PNG generation requires Playwright; missing dependencies trigger specific installation commands.
- The tool validates source files, rejecting gallery pages ([`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html)) and HTML lacking SVG elements.

## Frequently Asked Questions

### What file formats does diagram-design support for export?

Diagram-design supports **SVG** (vector) and **PNG** (raster) formats. You can export SVG only using `--svg-only`, PNG only using `--png-only`, or both simultaneously by omitting flags. The default behavior generates both files side-by-side.

### How do I set a custom resolution for my diagram export?

Use the **`--scale`** parameter with a value between 1 and 4. The tool multiplies your SVG's viewBox dimensions by this scale factor to determine final pixel size. For example, a 1280×720 viewBox with `--scale=2` produces a 2560×1440 PNG. Fractional scales like `1.25` are accepted for precise width targeting.

### Why can't I export PNG files in diagram-design?

PNG export requires Playwright. If you receive an error, run `pip install playwright` followed by `playwright install chromium` as specified in the error message from [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). Without this dependency, the tool can only generate SVG exports.

### Can I export multiple diagrams at once from a gallery page?

No. If you attempt to export [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) (which contains multiple SVGs), the tool refuses the operation and prompts you to select a specific diagram HTML file. This prevents accidental exports of gallery overview pages that contain more than one diagram element.