Skip to content
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. 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 in the fence immediately above it — 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
note api: rate limited 5/min
payload web->api: POST /login {email, pw}
```

Unknown lines are ignored, never fatal — a partial diagram still renders.