Syntax reference¶
This page collects the small authoring forms that are useful when moving from the guided tutorial to a real document. Every rendered card below is checked by the site build and carries the exact source into the editor.
Statement separators, comments, and continuation¶
Newlines and semicolons separate statements. // and # (when followed
by whitespace) are line comments; /* ... */ is a block comment. A trailing
backslash joins the next physical line into one logical statement:
Separators and comments
# a hash comment
/* a block comment */
A: box "A"; B: box "B" // an end-of-line comment
A -> B
Expressions and dimensions¶
Numeric expressions accept decimal and scientific literals, unary signs,
parentheses, and the ordinary +, -, *, and / operators. The
same expression forms work in width, height, size, textsize,
gap, and coordinate fields:
Numeric expression forms
base = 1.25e2
inset = -(1 + 2) * -3
A: box "decimal + scientific" width base / 2
B: box "unary + grouped" width base + inset height 40
C: box "all operators" width (base - 10) * 2 / 5 at (500, 120)
A -> B
B -> C
Placement fields are coordinates, named places, anchors, and between
expressions. at and with are equivalent placement forms for a shape:
Placement fields
A: box "source" with .nw at (40, 50)
B: box "target" at (420, 300)
Caption: text "between" at between(A, B, 1/2)
A -> B "anchors"
Sizing and text alignment¶
Boxes accept width and height (or the shared size qualifier), and
fill none leaves a shape unfilled. Text and edge labels accept all three
horizontal alignments and all three vertical alignments:
Size, fill, and alignment
A: box "wide" width 160 height 44 fill none
B: box "tall" size 72 fill #dbeafe at (320, 120)
text "left / top" align ljust valign top at (80, 220)
text "center / center" align center valign center at (300, 220)
text "right / bottom" align rjust valign bottom at (520, 220)
A -> B "styled edge" fill #fef3c7 align rjust valign bottom textsize 13 bold italic
Blocks and label styling¶
Square-bracket blocks are labelled containers. Their label supports fill, text size, weight, style, and alignment qualifiers. The same style qualifiers are accepted on boxes, standalone text, and edge labels:
Styled block and edge label
Region: [
A: box "api"
B: box "worker"
] "Service block" fill #336699 textsize 16 bold italic align center valign bottom
A -> B "edge label" fill #fef3c7 align ljust valign top textsize 12 bold
Arrows and route policy¶
The glyph form of an edge is [Name:] A -> B "label" modifier*. The glyph
carries the heads (->, <-, <->; -- is a line), the label
follows the endpoint it belongs to, a chain A -> B "x" -> C is one
statement per hop, and an endpoint that names no declared handle declares a
box. A quoted endpoint’s text is its handle:
Edge forms
A: box "source"
B: box "target"
C: box "review"
A -> B "named"
E: A -> C "named edge" route left
B <-> C "both heads"
"Audit" -- C
The word arrow form can add a bare direction such as right to author
its first departure direction (the edge’s heading intent). SheepText plans
the remaining bends and the arrival at the target. This example leaves the
source to the right and then turns toward the target:
Authored departure heading
A: box "source" at (80, 100)
B: box "target" at (360, 230)
arrow right from A to B
The four directional route policies prefer the side an edge should leave by. The final route can still differ when endpoint or layout constraints win; they are not a promise of one exact path. They are taught in Automatic layout and can be applied from the editor as described in Edit the diagram you see:
The layout chapter renders the below and left choices. These cards
show the other two sides with a flow that makes the detour easy to read:
Prefer an upper return route
direction right
A: box "client"
B: box "server"
A -> B "request"
B -> A "response" route above
Prefer a right-side return route
direction down
A: box "client"
B: box "server"
A -> B "request"
B -> A "response" route right
The direct/orthogonal route policies are parser forms retained for
the editor’s experiments. They are deliberately not presented as product
guarantees here because the shipped renderer does not promise a distinct
visible result for every combination:
A -> B "policy" route direct
A -> B "policy" route orthogonal
Layout direction and strength¶
Statement strength LEADS the statement: <strength> <relation>, never the
other way round. prefer is a soft preference, require is a hard
requirement, and writing neither means prefer. The name after row,
column, stage and group is optional:
Preferred and required alignments
row: A B
prefer column: C D
require row Locked: E F
A: box "implicit"
B: box "prefer"
C: box "column"
D: box "prefer"
E: box "required"
F: box "row"
direction, row, column and binary node order accept a strength.
stage and group do not; they declare a visible container rather than a
constraint the solver can fail to honour, and a strength written on one is
refused. Binary order relates two nodes along one axis; it does not align them
on a shared row or column. As with other constraints, prefer may degrade
with a warning while require refuses an impossible diagram:
Preferred and required node order
prefer Draft left of Review
require Publish above Archive
Draft: box "draft"
Review: box "review"
Publish: box "publish"
Archive: box "archive"
These feasible cards do not promise that every preference will hold. When a preference loses to a requirement, the diagram renders and the editor reports the degraded statement. An impossible set of requirements is refused with diagnostics anchored at the conflicting statements. The binary-order editor interaction is taught in Edit the diagram you see.
The product automatic-layout path demonstrates right/down directions. Lead with
prefer for a soft preference or require for a hard direction/row/column
requirement:
Preferred layout direction
prefer direction right
A: box "first"
B: box "second"
A -> B
require is a hard strength. This supported downward requirement is a
compact form that remains feasible for the automatic solver:
Required layout direction
require direction down
A: box "first"
B: box "second"
A -> B
The left and up direction tokens remain parser/reference forms. Their
automatic fallback is intentionally not a product quality promise, so they
are shown only as syntax:
prefer direction left
direction up
After automatic layout has produced a useful baseline, an authored path is
an explicit parser escape hatch for a route that must follow particular bends.
It is retained in the reference corpus but has no product card because current
production rendering does not guarantee a distinct visible route for every
authored path.
A.e -- B.w path right 80 then down 90 then right 60
Icons and source aliases¶
Built-in packs are the product-supported offline path. labelside accepts
left, right, top, and bottom. A remote source alias is retained
as a grammar/reference form but is intentionally not published here: a build
must never depend on an unavailable network pack. The editor can still show
the alias text when experimenting with a locally available pack.
Icon caption sides
use icons aws
L: icon aws:server labelside left "left" at (100, 150)
R: icon aws:server labelside right "right" at (280, 150)
T: icon aws:server labelside top "top" at (460, 150)
B: icon aws:server labelside bottom "bottom" at (640, 150)
Grammar-only reference (not a published render):
use icons "https://example.com/packs/cloud.json" as cloud
icon cloud:database