Skip to content
vizzy vizzy

vizzy file format

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

Frontmatter

Section titled “Frontmatter”

Every file starts with optional YAML frontmatter:

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

created and lastEdited are dates in YYYY-MM-DD form. Set created once; 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. This is for the diagram itself — the common, portable diagram types.
  • A vizzy fence is vizzy’s own mini-language. It does two things Mermaid can’t:
    1. a standalone architecture service map; and
    2. annotations layered onto the diagram or table in the fence immediately above it — title, desc, note, payload, style, hint, pos, layout.

Rule of thumb: reach for 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 tint 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, never fatal — a partial diagram still renders.

Node and edge labels are plain text — don’t put HTML in them. vizzy tolerates <br> (so pasted Mermaid renders), but use a desc subtitle instead; 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”

Three ways to add words to a diagram — pick by what they describe:

  • desc labels 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). Reach for it to title a box or a whole section, rather than pinning a note to one member node inside it.
  • note is a yellow card beside a node — a short aside or caveat worth seeing at a glance (rate limited 5/min), not the thing’s own description.
  • hint tucks deeper detail behind a click-to-open (?) badge — the why, a longer explanation, or a link to another file or diagram.

See the full directive reference for syntax.