Skip to content
vizzy vizzy

vizzy file format

A *.vizzy.md file is plain Markdown with diagram fences. It renders on GitHub and in any editor. vizzy adds a canvas on top.

Frontmatter

Section titled “Frontmatter”

Every file can start with optional YAML frontmatter:

---
title: Auth architecture     # optional
layout: LR                   # optional: TB (default, top to bottom) or LR (left to right)
created: 2026-06-16          # date the file was first written
lastEdited: 2026-06-16       # update to today's date on every edit
---

created and lastEdited are dates in YYYY-MM-DD form. Set created once and update lastEdited whenever the diagram changes. title and layout are optional.

Prose vs diagrams

Section titled “Prose vs diagrams”

The body is GitHub-Flavored Markdown. Prose renders as annotation cards. Fenced code blocks render as diagrams.

mermaid fences vs vizzy fences

Section titled “mermaid fences vs vizzy fences”

There are two kinds of diagram fence, and they do different jobs:

  • A mermaid fence holds standard Mermaid (a practical subset): sequenceDiagram, flowchart / graph, classDiagram, erDiagram, stateDiagram-v2, gantt, mindmap, conceptmap, pie, xychart-beta, timeline, journey, quadrantChart, gitGraph. Use it for the diagram itself.
  • A vizzy fence is vizzy’s own mini-language. It does two things Mermaid cannot:
    1. a standalone architecture service map; and
    2. annotations for the diagram or table in the fence directly above it: title, desc, note, payload, style, hint, pos, layout, and the table-specific tablewidths / cellstyle. See the directive reference for the full set.

Rule of thumb: use a mermaid fence to draw the diagram. Add a vizzy fence right after it only when you need an architecture map, or want to annotate, position, or color specific nodes.

```mermaid
flowchart LR
  web[Web] --> api[API] --> db[(Postgres)]
```


```vizzy
desc db: primary + read replica
note api: rate limited 5/min
payload web->api: POST /login {email, pw}
```

Unknown lines are ignored and never fatal. A partial diagram still renders.

Node and edge labels are plain text. Do not put HTML in them. vizzy tolerates <br> so pasted Mermaid renders, but a desc subtitle is better. Other tags render literally. vizzy lint flags them, along with broken file links and raw #hex colors.

desc vs note vs hint

Section titled “desc vs note vs hint”

There are three ways to add words to a diagram. Pick by what the words describe:

  • desc says what a thing is. It becomes part of the node or section: a subtitle under a node’s label, or under a group’s title (the gray box grows to fit). Use it to title a box or a whole section, instead of pinning a note to one node inside it.
  • note is a yellow card beside a node. Use it for a short aside or caveat worth seeing at a glance, such as rate limited 5/min, not for the thing’s own description.
  • hint puts longer detail behind a click-to-open (i) badge: the why, a longer explanation, or a link to another file or diagram.

See the directive reference for syntax.