Gotchas

modl's parser is deliberately simple, and a few of its rules produce surprising results. Each gotcha below has an example you can open to see the behavior, plus a workaround. Many of them are avoided by quoting the label or id.

1. -> in a label makes an edge
2. Space before # starts a comment
3. Out-of-order attributes become text
4. Labels that start with a keyword
5. Words in the middle of a chain are ignored
6. A color alone on a line is a background
7. Keywords are case-sensitive
8. Ids can't contain dots or spaces
9. A bad id in a chain joins its neighbors
10. A dangling arrow
11. Attributes can't be removed by redefining
12. Edge size doesn't thicken lines
13. Repeated, reverse and self edges overlap
14. Long labels are truncated
15. Image node quirks
16. A leading / means https
17. Renaming a node loses its position
18. Edges run into wide nodes
19. A quote at the start of a word opens a string

1. -> in a label makes an edge

Any line containing -> outside quotes is an edge line, even when the arrow is meant as text. Below, the first line was meant to be a node labeled "Input -> Output". Instead it creates an edge from step to a new node named Output, and "square Input" is silently dropped.

step square Input -> Output

Workaround: quote the label, or use a Unicode arrow such as →.

step1 square "Input -> Output"
step2 square Input → Output

2. Space before # starts a comment

Outside quotes, whitespace followed by # ends the line. The label below is only "Fix issue".

bug square red Fix issue #42

Workaround: quote the label or the word with the #, or keep the # attached to the previous word.

bug1 square red "Fix issue #42"
bug2 square red Fix issue "#42"
bug3 square red Fix issue#42

3. Out-of-order attributes become text

Attributes must come in the order size, style, color, URL. A word after its slot has been passed is label text, along with everything after it, URLs included.

a red square /example.com Home    # label is "square /example.com Home", no link

a square red /example.com Home

See Attributes for more examples.

4. Labels that start with a keyword

If the label's first word is a reserved word for a slot that hasn't been passed yet, it becomes that attribute.

a big data
b red alert

Workaround: quote the word, fill a later slot (for example with the default color gray), or capitalize the word.

a "big data"
b gray red alert
c Big Data

5. Words in the middle of a chain are ignored

In a … -> b … -> c …, only the last segment's attributes count. Everything after the id in earlier segments is dropped without an error.

a -> b red -> c dashed

Workaround: write differently styled edges on separate lines.

a -> b red
b -> c dashed

6. A color alone on a line is a background

A line holding just a color name sets the background, so it can't declare a node called red.

red
red -> green

Workaround: quote the id, give the node any attribute, or create it with an edge only.

"red"
red -> green

7. Keywords are case-sensitive

Big, Square and Red aren't keywords, so they become the label.

a Big Square Red

a big square red

8. Ids can't contain dots or spaces

Unquoted ids allow only letters, digits, _, : and -. A line starting with something like a domain name or version number is an error.

example.com square blue
v1.2 -> v1.3

Workaround: quote the id, or use a simple id and put the real name in the text.

"example.com" square blue
"v1.2" -> "v1.3"
site square blue example.com

9. A bad id in a chain joins its neighbors

When an id in the middle of a chain is invalid, the editor reports an error but still draws the chain without that node, connecting the ids on either side. An invalid last id discards the whole line instead. Quote the id to keep it in the chain: a -> "b.x" -> c.

a -> b.x -> c

10. A dangling arrow

A line with an arrow but only one id, like a ->, is a malformed edge line error. Empty segments are skipped, though, so a -> b -> and a -> -> b both quietly mean a -> b.

a ->
b -> c ->
d -> -> e

11. Attributes can't be removed by redefining

A later node line only overrides the attributes it gives. A bare id doesn't reset anything.

n big square red Label
n

Workaround: set attributes back explicitly (normal, circle, gray, and "" for the text) or delete the earlier line.

n big square red Label
n normal circle gray ""

12. Edge size doesn't thicken lines

On edges, size only scales the label. For a thicker line use bold.

a -> b huge heavy?

a -> b bold heavy

13. Repeated, reverse and self edges overlap

Edges are straight lines, so two edges between the same nodes are drawn on top of each other. Reverse edges overlap too, giving a double-headed arrow. A self edge like a -> a has no length, so its arrowhead and label are drawn on top of the node, covering the node's label.

a -> b red one
a -> b blue two
b -> a green back
a -> a self

Workaround: combine parallel labels into one edge, or route through an extra node with shape none.

via1 small none red fast
via2 small none blue cheap
a -> via1 red
via1 -> b red
a -> via2 blue
via2 -> b blue

14. Long labels are truncated

Node labels show at most 22 characters and edge labels 28. The rest is replaced by …, and the full text shows on hover.

a square A rather long name for a node
b square Short
a -> b This edge label is also quite long

Workaround: keep labels short, or put details in a linked page.

15. Image node quirks

• The default shape isn't drawn around an image. A frame appears only when you write a shape.
• Without text, an image node has no visible label, not even its id.
• Without a size, an image is drawn at its natural size, which may be huge.
• Every http(s) URL on a node is test-loaded as an image, so the browser contacts those sites when the diagram opens.

a /curtcox.github.io/modl/docs/img/cloud.svg
b circle teal /curtcox.github.io/modl/docs/img/cloud.svg Cloud
a -> b

16. A leading / means https

/example.com/page is shorthand for https://example.com/page, not a path on the current site. There is no relative-link form. A URL can't contain spaces, since the first space ends it. Quoting doesn't help, because a quoted word is always text; write spaces as %20.

a /docs/intro.html Not a relative link
b /my page.html Space ends the URL

17. Renaming a node loses its position

Positions are stored by id. Changing an id, even its case, creates a new node that is placed automatically, and the old position is discarded. To relabel a node without moving it, change its text instead of its id.

18. Edges run into wide nodes

An edge stops at a fixed distance from a node's center rather than at its outline. A square is wider than that distance, so a line arriving from the side runs into the box and can cross the label. Large nodes make it worse.

a big square blue Source system
b big square purple Target system
a -> b

Workaround: place connected squares above and below each other rather than side by side, or use circles, which the lines don't enter.

a big square blue Source system
b big square purple Target system
a -> b

19. A quote at the start of a word opens a string

A " or ' at the start of a word opens a string if the same quote appears anywhere later on the line, even in the middle of another word or in what would otherwise be a comment. Below, the leading apostrophes of 'tis and 'twas pair up and disappear. In the second line, the single-quoted string ends at the apostrophe in Bob's.

a 'tis and 'twas
b 'Bob's car'

Workaround: put text with apostrophes in double quotes, and text with double quotes in single quotes.

a "'tis and 'twas"
b "Bob's car"