Diagram annotations in vizzy

Annotations are numbered pins you drop anywhere on a diagram to leave a comment — the same idea as marking up a screenshot in a design review. They’re for talking about a diagram, separate from the desc/note/hint directives that are part of the diagram’s own source.

Adding a pin

Click the comment button (the ＋-bubble icon) in the document toolbar to enter pin mode, then click anywhere on the canvas to drop a numbered pin. A small popover opens for you to type the comment.

Pins are anchored in the diagram’s own coordinate space, so they stay attached to the spot you placed them even as the diagram is edited and re-laid-out.

Comment on prose

You can also comment directly on the words in a prose block — no pin mode needed. Select some text and a small Add comment bubble appears; click it to drop a numbered pin anchored to that passage, with the quoted words highlighted in yellow.

Because a prose comment is anchored to its quote (and the text around it) rather than to a point on the canvas, it survives edits elsewhere in the file — the highlight stays on the right words as the rest of the document changes. Open the pin and it shows the passage it’s attached to; if that text is later deleted or rewritten so the quote no longer resolves, the comment is flagged as Original text changed rather than silently pointing at the wrong place.

Where pins are stored

Annotation pins are saved to a sidecar file next to the .vizzy.md, so they persist across restarts without changing the diagram source itself. Because they live beside the file rather than inside it, the rendered diagram and the CLI render output stay clean — pins are a reviewing layer, not part of the published image.

Editing a prose block inline

Reviewing often turns into fixing. Double-click a prose block to edit its Markdown right on the canvas — the block turns into an editor. Click away or press ⌘-Return to commit your change, or Esc to cancel. Unlike a comment, this edits the .vizzy.md file itself.