Rendering to images

The vizzy CLI can render any .vizzy.md file to images — no window, no Screen Recording permission, no manual screenshotting. This is the piece that lets a coding agent author a diagram and then drop the rendered image into your repo’s assets/ folder in one step. PNG is the default; pass --format for JPEG, TIFF, HEIC, or AVIF.

(Not installed yet? See the Introduction to add the vizzy command.)

Render a file

vizzy render vizzy/architecture.vizzy.md

By default each diagram in the file becomes its own PNG, written to a sibling assets/ folder next to the file:

vizzy/
  architecture.vizzy.md      # say this holds 3 diagrams
  assets/
    architecture-overview.png
    architecture-data-flow.png
    architecture-deploy.png

Each image is named <file>-<diagram-slug>.png, where the slug comes from the diagram’s title (a diagram with no title falls back to its index, e.g. architecture-0.png). Two diagrams sharing a title get a -2, -3, … suffix.

Options

Option	Default	Description
-o, --out-dir <dir>	<file's dir>/assets	Where to write the images.
-f, --format <fmt>	png	Output format: png, jpeg, tiff, heic, or avif. Sets both the encoding and the file extension.
--quality <0–1>	0.9	Compression quality for the lossy formats (jpeg, heic, avif). Ignored for png/tiff.
--scale <n>	2	Pixel scale factor (2 = retina-quality).
--whole-doc	off	Render the whole file as a single tall image instead of one image per diagram.
--dark	off	Render in dark mode (dark background, light strokes and text).
--light	on	Render in light mode. This is the default.
-h, --help		Show usage.

You can pass several files at once, or a directory — a directory renders every *.vizzy.md it contains (recursively):

vizzy render vizzy/                       # the whole folder
vizzy render vizzy/auth.vizzy.md vizzy/checkout.vizzy.md -o build/diagrams
vizzy render vizzy/architecture.vizzy.md --whole-doc --scale 3
vizzy render vizzy/architecture.vizzy.md --dark    # dark-mode PNGs
vizzy render vizzy/architecture.vizzy.md --format avif   # small modern image

Image formats

Use --format (or -f) to choose the output codec; the file extension follows automatically.

Format	Extension	Notes
png	.png	Lossless, the default. Best for crisp diagrams and broad compatibility.
jpeg	.jpg	Lossy, smallest legacy option. Tune with --quality.
tiff	.tiff	Lossless, uncompressed — large files, mainly for print/archival pipelines.
heic	.heic	Lossy, much smaller than JPEG at the same quality.
avif	.avif	Lossy, the smallest option and well-supported by modern browsers — the best pick for the web.

vizzy render vizzy/auth.vizzy.md --format avif                 # smallest, modern
vizzy render vizzy/auth.vizzy.md --format jpeg --quality 0.8   # smaller JPEGs

Why no WebP?

macOS can read WebP but ships no WebP encoder, so Vizzy can’t write .webp. AVIF is the native answer — it produces smaller files than WebP with the same modern-browser support, so reach for --format avif wherever you’d have used WebP.

The agent loop

This closes the loop for a coding agent maintaining your diagrams:

1. Write or update vizzy/<flow>.vizzy.md.

2. vizzy render vizzy/<flow>.vizzy.md → PNGs land in vizzy/assets/.

3. Reference the PNG from your README, docs, or web page:

   ![Auth architecture](vizzy/assets/auth-overview.png)

Every render prints the path it wrote (vizzy: rendered …) so the agent knows exactly which file to embed. Run vizzy lint first to catch problems the renderer would otherwise swallow silently.

Note

Prefer the interactive app for live editing — it live-reloads as you type. The CLI is for producing shareable images: committing diagrams to docs, embedding them on the web, or generating them in a build step.