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

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 and 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, 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:

diagram-design export diagram.html

Generate only an SVG for version control:

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

Create a high-resolution PNG for print media:

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

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

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

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

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:

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 (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.
• 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) 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. 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 (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.

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