Rendering to images

The vizzy CLI renders any .vizzy.md file to images. No window, no Screen Recording permission, no manual screenshots. This lets a coding agent write a diagram and put the rendered image in 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 an 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. The slug comes from the diagram’s title. A diagram with no title uses its index instead, for example architecture-0.png. Two diagrams with the same 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 format. The file extension follows automatically.

Format	Extension	Notes
png	.png	Lossless. The default. Best for crisp diagrams and broad compatibility.
jpeg	.jpg	Lossy. The smallest legacy option. Tune with --quality.
tiff	.tiff	Lossless and uncompressed. Large files, mainly for print or archival pipelines.
heic	.heic	Lossy. Much smaller than JPEG at the same quality.
avif	.avif	Lossy. The smallest option, well supported by modern browsers. The best choice 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 has no WebP encoder, so Vizzy cannot write .webp. Use AVIF instead. It produces smaller files than WebP with the same modern-browser support.

The agent loop

A coding agent maintaining your diagrams can:

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

2. Run vizzy render vizzy/<flow>.vizzy.md. PNGs are written to 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 which file to embed. Run vizzy lint first to catch problems the renderer would otherwise ignore.

Note

Use the app for live editing. It 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.