Documentation

Every definition file starts with a mode keyword, followed by an optional title in quotes. Indentation is not significant. Blank lines and lines beginning with # are ignored.

Modes

Keyword	Produces	Notes
`topology`	Boxes and arrows	Layered layout, longest path becomes the primary axis
`sequence`	Lifelines and messages	Supports activation bars and nested blocks
`depends`	Directed graph	Reports cycles instead of drawing them

Edges

An edge is two names joined by an arrow. Everything after the arrow target is treated as modifiers, in any order.

worker -> store              # plain edge
worker -> metrics  dashed    # line style
queue  -> worker   x3        # multiplicity badge on the target
api    -> db       "reads"   # quoted label

Modifier	Effect
`dashed`, `dotted`	Line style
`xN`	Draws the target once with a multiplicity badge
`"text"`	Edge label, placed at the midpoint
`<->`	Bidirectional; arrowheads on both ends

Groups

A group draws a labelled boundary around named nodes. Groups may not overlap; a node listed in two groups is a parse error rather than a best-effort drawing.

group "hot path" { edge queue worker }
group "storage"  { store replica }

Sequence mode

In sequence mode the arrow direction sets message order top to bottom. A block wraps a run of messages in a labelled frame.

sequence "token refresh"

  client -> gateway  "POST /refresh"
  gateway -> authsvc "validate"

  block "on expiry" {
    authsvc -> store  "revoke"
    authsvc -> client "401"
  }

  authsvc -> gateway "new token"
  gateway -> client  "200"

Command line

nuxtgram render  diagrams/ -o build/diagrams/
nuxtgram render  ingest.ngm -o ingest.svg
nuxtgram check   diagrams/          # parse only, non-zero exit on error
nuxtgram fmt     diagrams/ --write  # canonical spacing and alignment

--width N: Target width in pixels. Layout reflows to fit; it never scales the output after the fact, so text stays at its natural size.
--theme light|dark|both: With both, a single SVG carries a media query and adapts to the reader's colour scheme.
--seed N: Overrides the fixed layout seed. Changing it reshuffles tie-breaking between equally-ranked nodes; leave it alone unless a diagram is stuck in a layout you dislike.
--strict: Turns warnings — unused nodes, duplicate edges, empty groups — into errors. Recommended in continuous integration.

Exit codes

Code	Meaning
`0`	All inputs rendered
`1`	Parse or layout error; message names the file and line
`2`	Cycle detected in `depends` mode
`3`	Output path not writable

Known limitations

Dependency mode reports cycles rather than laying them out. Sequence diagrams beyond roughly forty messages produce a very tall SVG with no pagination. Right-to-left text is not shaped correctly and is currently rendered left-to-right with a warning under --strict.