nomnoml Syntax: Every Arrow, Shape and Directive, Tested

You copy a class diagram from an old wiki page into nomnoml and get Parse error at line 1 column 5, expected "label" but got ">". The line was [a] _> [b], an arrow the first syntax list on Google still shows. nomnoml stopped understanding it in version 1.6.0, in May 2023.

The other lists are incomplete rather than wrong: they name directives without saying what they do, show example values instead of defaults, and skip escapes, ids and errors. So we installed nomnoml 1.7.0, the current release on npm, read its parser, and ran every arrow, shape and directive through renderSvg on 27 October 2026. The method is under how we tested.

The whole syntax on one screen

If you remember six things, remember these:

• A box is text in square brackets. [Order] is a box. Its first line is its name, and the name is also how other lines refer to it.
• | splits a box into compartments, usually name, fields, methods: [Order|id;total|place()].
• ; or a new line starts the next line inside a compartment.
• A link is box, arrow, box, with optional labels on both sides: [Order] 1 +- 0..* [Line].
• A shape type goes right after the bracket: [<actor>Shopper], [<database>orders].
• A directive is a line that starts with # in the first column: #direction: right.

Boxes can contain whole diagrams, too. [<frame>Checkout|[API] -> [Basket]] draws a frame with two linked boxes inside it, and each level of nesting takes the next colour from #fill.

All 18 arrows

An arrow has three parts: an optional start (<, <:, +, o, o< or (o), a line (- solid, -- dashed, -/- hidden) and an optional end (>, :>, +, o, >o, ) or o)). The parser glues the parts together, which is why <-> and +-> work without a list entry of their own. Below are the 18 combinations the nomnoml README lists, each drawn between two boxes.

<- works too, because it is just a start and a line, although the lists do not mention it. The hidden link is more useful than it looks: it pulls two boxes into the same column or row without drawing anything.

Two arrows from old lists no longer exist. The R package’s syntax page lists _> as a “weightless edge” and __ as a “weightless dashed” edge, which let two linked boxes sit on the same level. They came out of nomnoml issue #141 in 2020, together with a directive the maintainer described there: “I did implement a #gravity: 0 directive that sets minlen = 0 on every edge.” We installed the old releases to check: _> renders in 1.5.0 and 1.5.3 and gives a parse error from 1.6.0 (May 2023), whose new parser has no _. That includes 1.6.2, the version the R package itself bundles, so its own page lists edges its renderer rejects. Use #gravity: 0 instead.

All 25 shapes

The shape type goes between < and > straight after the opening bracket. Most of them come from UML class, activity, component and use case diagrams.

The table shape is the odd one: inside it, | separates cells and || ends a row, so [<table>t|a|5||b|7] draws a title t above two rows, a 5 and b 7.

Text inside a box: compartments, lines and escapes

Inside the brackets, three characters have a job: | starts the next compartment, and ; or a line break starts the next line. So these two are the same box:

[Order|id: string;total: Money|place();cancel()]

[Order|
  id: string
  total: Money|
  place()
  cancel()
]

To print one of the special characters, put a backslash in front of it: \|, \;, \[, \]. [A|a \| b] prints “a | b”, and [A|list\[0\]] prints “list[0]”. \n is the one escape with a meaning of its own: it becomes a line break character, but the SVG renderer prints it as a space, so [two\nlines] shows “two lines” on one line. For a title on two lines use ;: [two;lines] draws both lines in the title, and the box’s id is the first one, two. Text that is not Latin needs nothing special; [Задача] -> [完成] renders as typed.

Labels on links follow stricter rules. The text before an arrow may not contain [ ] | < > ; at all, so [a] x<y -> [b] fails with expected "label" but got "<". Escape it: [a] x\<y -> [b]. The text after the arrow may contain anything except [, which starts the target box.

Names, ids, and boxes you mention twice

A box’s id is its first line. Write [Order] on one line and [Order|id;total] on another and you get one box, not two. When the same box appears with different contents, nomnoml keeps the version with more compartments, in whichever order they come. That is what makes the common style work: describe each class once in full, then link it by name alone.

[Order|id: string;total: Money|place()]
[Customer|name: string]
[Customer] 1 - 0..* [Order]

When two different boxes need the same name, give them ids. The id goes in the shape tag and other lines refer to it, while the box still shows its name:

[<actor id=buyer>User]
[<actor id=seller>User]
[buyer] -> [<usecase>Pay]
[seller] -> [<usecase>Ship]

An id may only use letters, digits and _, and an attribute value may not contain a space or >.

Directives: what each does, and the real default

The help panel on nomnoml.com and the README show each directive with a value next to it. Those are examples, not defaults: the panel shows #gutter: 5 and #font: Calibri, while 1.7.0 uses 20 and Helvetica when you leave them out. The defaults below are read from the 1.7.0 source.

Three rules apply to all of them. The # must be the first character of the line; an indented directive is not a directive (see the traps). The last one wins when the same directive appears twice. And numbers fall back to the default when they are 0 or not a number: #lineWidth: 0 and #padding: 0 draw exactly what the defaults draw. #edgeMargin and #gravity are the exceptions where 0 does something, because their defaults are 0 and 1.

#ranker is worth trying when a diagram looks tangled. Its three values are the ways the bundled layout library, graphre, can assign boxes to levels, and each places the same boxes differently.

Custom styles

A directive whose name starts with a dot defines a shape type of your own:

#.risk: fill=#fde68a stroke=#b45309 dashed title=bold,italic
#.service: visual=roundrect direction=right
[<risk>Single point of failure]
[<service>Checkout|[API] -> [Basket]]

The keys are fill, stroke, visual (which built-in drawing to use, such as class, roundrect, ellipse, database, rhomb or actor), direction for a nested diagram, and align=left. title= and body= take a comma-separated list of bold, italic, underline, left and center. dashed on its own makes the border dashed.

Two limits are not in the docs. The style name may only use letters, digits and _: #.my-box makes [<my-box> A] fail with expected " " or ">" but got "-". And the empty modifier, which the README lists next to dashed, has no effect in 1.7.0: a diagram with empty draws exactly the same SVG as one without it.

15 traps we found by running 1.7.0

Each row is a probe we ran. The middle column is what nomnoml 1.7.0 did.

Indented comments, on the other hand, are fine: the parser strips lines that start with spaces and //. So you can indent comments inside a nested diagram, just not directives.

The SVG renderer colours every arrowhead the same

This one is easy to miss, because the diagram looks almost right. In SVG output, the arrowheads and the link labels of a diagram all get one fill colour: the colour of the last arrowhead drawn. A generalization triangle is meant to be hollow (filled with the box colour) and an open arrowhead solid (the line colour). Put both in one diagram and one of them comes out wrong.

We measured the fill of every head and label in 15 combinations. The pattern:

• Write the triangles last, and the triangles are right, but plain arrowheads turn hollow and labels turn pale.
• Write them first, and arrowheads and labels are right, but the triangles turn solid.
• Diamonds are always right (+-, o-): the renderer saves and restores the colour around them.

The cause is in drawArrow, which sets the fill without saving and restoring it, while the SVG backend writes the fill on the group that holds all the links. A diagram with inheritance and no labels or open arrowheads, like the class diagram below, is not affected. For one that has all three, write the inheritance links first and accept solid triangles; their shape still reads as inheritance. We found no issue for this in the nomnoml tracker on 27 October 2026.

<end> has the same cause. It is meant to be a dot in a ring: the code draws a circle in the box colour, switches to the line colour, and draws a smaller dot. In SVG both come out in the line colour, so an end looks like a slightly smaller start.

Reading the error messages

nomnoml stops at the first error and names the line, the column, what it expected and what it found. Three messages cover most mistakes:

• expected "]" but got end of file: a bracket is not closed somewhere in the source. Count the [ and ] of nested boxes first.
• expected "label" but got ...: the parser was reading the text before an arrow and met a character that cannot be there. Either the arrow is not one nomnoml knows, or a label contains [ ] | < > ; without a backslash.
• expected "--" or "-/-" ...: there is text after a link where a new line was expected, often a comment at the end of a line.

An empty source is not an error; it renders an empty drawing.

Three diagrams to copy

All three were rendered with 1.7.0 and checked for the arrowhead trap.

A class diagram with an abstract class, inheritance, composition and aggregation:

#direction: down
[<abstract>Payment|amount: Money;currency: string|capture();refund(amount)]
[Order|id: string;total: Money|place();cancel()]
[Order] +- [LineItem|sku: string;quantity: int]
[Order] o- [Customer]
[Order] - [Payment]
[Payment] <:- [CardPayment|last4: string]
[Payment] <:- [BankTransfer|iban: string]

A flow chart with a decision and a loop back:

#direction: down
[<start>start] -> [Review the pull request]
[Review the pull request] -> [<choice>Tests pass?]
[Tests pass?] no -> [Fix the build]
[Fix the build] -> [Review the pull request]
[Tests pass?] yes -> [Merge]
[Merge] -> [<end>end]

A component view with a nested diagram, a database and a required interface:

#direction: right
[<frame>Checkout service|
  [API] -> [Basket]
  [Basket] -> [<database>orders]
]
[Checkout service] -o) [Payments gateway]
[<actor>Shopper] -> [Checkout service]

Where nomnoml runs

In the SVG output, each box’s shapes carry a data-name attribute with the box’s name, so a web page can make a diagram clickable without parsing the drawing.

nomnoml in Jira and Confluence

Neither Jira nor Confluence draws nomnoml on its own. We make two apps that do: Excalidraw UML & Class Diagrams for Confluence and for Jira. Their nomnoml editor passes your text to the same renderSvg of nomnoml 1.7.0 that this guide tested, with nothing changed, so every example here renders the same way there. That includes the arrowhead trap, so write the inheritance links first in those apps too.

The difference from nomnoml.com is what happens around the diagram. It is stored with the Confluence page or the Jira issue, its source stays editable (choose Update and change the text), and you can sketch around it in Excalidraw: circle the class a bug report is about, or add a hand-written note next to a link. The same editor has Mermaid for the sequence diagrams nomnoml cannot draw. Everything renders in your browser and is stored in your Atlassian site; the apps make no external calls. Both are free for up to 10 users: install for Confluence or install for Jira.

If your team used nomnoml tabs in Issue Tabs for Jira, those tabs keep working; new tabs there use Mermaid, Graphviz and the other types.

How we tested

• Version. nomnoml 1.7.0 from npm (npm view nomnoml version on 27 October 2026), the copy our Excalidraw UML apps ship, with graphre 0.1.3, on Node 24.
• Method. For each probe we called renderSvg and either recorded the error message or compared the SVG with a reference source, after removing the <desc> element in which nomnoml embeds the source text. “Identical” in this guide means byte for byte identical SVG. For the arrowhead trap we walked the SVG and recorded the effective fill of every closed path and every label.
• Source code. Defaults, the directive rules and the escape rules come from getConfig, extractDirectives and linearParse in dist/nomnoml.js of 1.7.0. The R package’s bundled version comes from its inst/htmlwidgets/nomnoml.yaml on GitHub; its version and date from CRAN. For _> we installed nomnoml 1.5.0, 1.5.3 and 1.6.0 from npm and rendered the same two lines.
• Not tested. PNG export on nomnoml.com, and versions other than 1.5.0, 1.5.3, 1.6.0 and 1.7.0.