flowchart
A canvas environment that draws a flowchart, tree or entity–relationship diagram from boxes and arrows.
flowchartOn this page


#Boxes and arrows
flowchart draws a flowchart, a tree or an entity–relationship diagram, written as what connects to what and never as coordinates. box declares a thing and arrow a relation between two of them, by the boxes' ids; the environment places the boxes and routes the arrows. A logic circuit is drawn in a logic environment.


flowchart{
box#sample:terminal{Sample collected}
box#pcr{
PCR amplify
30 cycles
}
box#check:decision{Enough DNA?}
arrow(from: #sample; to: #pcr)
arrow(from: #pcr; to: #check)
arrow(from: #check; to: #pcr; label: no; dashed)
}(
direction: down
)A box's body is its text, rich inline, so maths, bold and {{…}} all work. Its first line is the label and every further line is set smaller and muted beneath it; text wider than the widest box wraps. An arrow's ends must be boxes in the same environment; to: #qc with no box#qc beside it is refused: 'arrow.to' names '#qc', but no box in this environment declares that id.
head says which ends of an arrow point: end (the default, at to), start, both or none. The boxes are ranked from from to to whichever it is. label sets words in a chip on the arrow's line, and from-label and to-label set words beside the line where it leaves its first box and where it meets its second.
#Shapes
shape is the implicit attribute, so box#check:decision{Enough DNA?} reads as the diamond it draws. The flowchart shapes are box (the default, a rounded rectangle), decision (a diamond), terminal (a pill) and ellipse. A decision's arrows leave by its vertices: one by the front vertex, two by the side vertices, and more by the sides with the rest spread about the front.
#Entity–relationship diagrams
Chen's shapes draw an entity–relationship diagram: entity and weak-entity (a rectangle, doubled), relationship and identifying-relationship (a diamond, doubled), attribute, multivalued-attribute (an ellipse, doubled) and key-attribute (an ellipse with its label underlined). Chen's links are plain lines, head: none, with a cardinality beside the entity it qualifies as the arrow's from-label or to-label.


flowchart{
box#emp:entity{Employee}
box#id:key-attribute{Employee ID}
box#phones:multivalued-attribute{Phone numbers}
box#has:identifying-relationship{Has}
box#dependant:weak-entity{Dependant}
box#works:relationship{Works for}
box#dept:entity{Department}
arrow(from: #emp; to: #id; head: none)
arrow(from: #emp; to: #phones; head: none)
arrow(from: #emp; to: #has; head: none; from-label: 1)
arrow(from: #has; to: #dependant; head: none; to-label: $N$)
arrow(from: #emp; to: #works; head: none; from-label: $N$)
arrow(from: #works; to: #dept; head: none; to-label: 1)
}(
direction: down
)#Layout
#Direction and ranks
The boxes are set in ranks along direction, the implicit attribute: down, up, right or left, so flowchart:right{…} reads left to right. Each arrow runs from one rank to a later one, and a tree is the same arrangement with every arrow pointing one way. Where arrows form a cycle, the one that closes it, found by following arrows in the order they are written, runs back against the flow.
Unwritten, direction is auto: the environment lays the whole chart out both down and right and keeps whichever draws it larger on the reader's screen, and on a tie whichever folds it less. It chooses again only when the room changes, never from step to step.
Chains that share no arrow are ranked apart and stand side by side across the flow, in the order their first box is written: columns under down, rows under right. A box with no arrows is a chain of its own.
#Arrow routes and labels
Arrows run through the gaps between ranks, never across a box and never along another arrow. An arrow leaves the front of its box and lands on the back of the next: one arrow at the middle of a face, several evenly spaced about it in the order of the boxes at their other ends. The boxes are placed so those points line up, and an arrow whose ends line up is straight; one whose ends cannot turns once, on a track of its own. An arrow that skips ranks runs through the gap beside the ranks it passes.
An arrow back against the flow leaves its box by the side, climbs beside the ranks between and lands on the earlier box's back. An arrow from a box to itself leaves by the side and loops round into the box's back.
A label's chip sits on the arrow's own run near where it leaves, clear of the other lines and chips; failing that, near where it lands; failing both, just beside its line.
#Wrapping a long chart
A chart longer than the environment has room for folds into lines. The environment weighs folding against shrinking, and prefers a fold to shrinking the chart by more than a few per cent. No line holds a single rank, so a chart of three ranks or fewer never folds; it shrinks.
Plain, a fold snakes: the next line reads back the other way, and the arrows across the fold drop past the ends of both lines and turn into the next. In a chart of exactly two lines, an arrow back from the second line to the first may run over the top instead, where that way is no longer. A strictly- direction (strictly-down, strictly-up, strictly-right, strictly-left) keeps every line reading the one way, each starting again at the beginning beside the last, like lines of text, and the arrows across a fold run back along the gap between the lines.auto never chooses a strictly- direction.


flowchart{
box#sample:terminal{Sample collected}
box#extract{DNA extracted}
box#pcr{PCR amplify}
box#gel{Gel check}
box#library{Library prep}
box#sequence{Sequencing}
box#align{Read alignment}
box#call{Variant calling}
box#report:terminal{Report}
arrow(from: #sample; to: #extract)
arrow(from: #extract; to: #pcr)
arrow(from: #pcr; to: #gel)
arrow(from: #gel; to: #library)
arrow(from: #library; to: #sequence)
arrow(from: #sequence; to: #align)
arrow(from: #align; to: #call)
arrow(from: #call; to: #report)
}(
direction: right
)#Groups and hues
A box says what kind of thing it is with group, and boxes of one group share a hue. The footer keys each group beside a disc in its hue, and !legend turns the key off. The environment's key is a map from the groups whose colour means something to their colours, key: (Quantitative: blue; Qualitative: teal) (Attributes), and every other group takes the key's otherwise, key: (Quantitative: blue; otherwise: grey), keyed once as other. Without one, every other group is dealt the next hue no pin has taken, in the order blue, orange, teal, pink, purple, green, red, yellow. A box's own colour wins over its group's.
Hovering a box dims everything but the box and what lies downstream of it; hovering an arrow lights it and its two ends.
#Cues and the camera
#Cues and the glide
Only what is on show is placed. A box or arrow that a cue has not yet brought in, has taken out, or that is hidden at the step takes no room, and an arrow is off show whenever either of its boxes is. The ranks and their order are taken from the whole chart, so as a cue brings a box in the rest glide aside to make room without being rearranged, and the newcomer fades in as they land.
cue.draw strokes an arrow in along its length. Around several boxes and arrows it draws them along the flow, each rank starting before the last has finished and each arrow just after the box it leaves. A dashed arrow fades instead, since a dash pattern and the drawn stroke cannot share one line.
#focus, zoom and interactive
focus names a box for the camera to look at, and zoom multiplies over the fitted frame; omitted, the chart fits the environment. Both are animatable, so a !cue.to on each glides into one part of a large chart as the narrative reaches it. interactive hands the reader wheel-zoom and drag, from the fitted frame up to eight times closer, with a double-click back to the authored frame; continue: #id carries the reader's camera on from an earlier flowchart.
flowchart:down{
box#sample:terminal{Sample collected}
box#pcr{PCR amplify}
box#check:decision{Enough DNA?}
arrow(from: #sample; to: #pcr)
arrow(from: #pcr; to: #check)
}(
focus: #sample !cue.to{#check}(at: 1; duration: 800ms)
zoom: 2
)#Attributes
directionautodownuprightleftstrictly-downstrictly-upstrictly-rightstrictly-leftflowchart:valueautotitlekeymaplegendtruefocuszoominteractivefalsecontinue#Allowed content
#Allowed in
#Examples


flowchart{
box#sample:terminal{Sample collected}
box#pcr{
PCR amplify
30 cycles
}
box#check:decision{Enough DNA?}
arrow(from: #sample; to: #pcr)
arrow(from: #pcr; to: #check)
arrow(from: #check; to: #pcr; label: no)
}(
direction: down
)

flowchart{
box#question:terminal{Question}
box#hypothesis{Hypothesis}
box#experiment{Experiment}(colour: teal)
arrow(from: #question; to: #hypothesis)
arrow(from: #hypothesis; to: #experiment)
arrow(from: #experiment; to: #hypothesis; label: revise; dashed: true)
}(
direction: right
title: The scientific method
)

flowchart{
box#dna{DNA}
box#rna{RNA}
cue.draw{
arrow(from: #dna; to: #rna; label: transcription)
}(
in: 1
)
}(
direction: right
)#Writing guidance
- Selecting canvas content — A mark belongs on the canvas when seeing it changes what the reader understands, and the detail holds as a picture on its own.