Roughout supports fourfive diagram types:
type: flowchart for step-by-step processes and decisions,
type: sequence for messages passing between participants over time,
type: gantt for project planning, i.e. tasks against a calendar timeline,
type: mindmap for a central topic with branches radiating outward.,
type: swimlane for a process split into lanes — who does each step, and where work hands off.
Philosophy
- Start typing, diagram draws, export/print, save to your file-system, close the tab. Nothing is saved until you choose to save it — there's no setup first.
- Plain text is a real diagram. Every line means exactly what it says — the tool never guesses what you meant.
- Start simple, add precision only when you need it. A bare line becomes a box automatically; specific syntax is there when you want more control, never required.
Focus and Error highlighting
Don't panic! It's just text. You can (and should) save multiple version copies as you go when you are drawing more complicated diagrams.
To help you, we have focus and error highlighting
- The 'current' line highlights in yellow, to help you track your place.
- The current line's diagram element is also highlighted (border).
- Errors are highlighted with red text as soon as we detect them. Note: this is not completely foolproof!
Flowchart diagram format
type: flowchart (the default) — step-by-step processes and decisions. The only one of the four with mouse editing: click to select, drag to move, right-click to create.
Start simple
box 1
box 2- A plain text line is just a box label. Subsequent lines are auto-connected by arrows
Comments
// a note to yourself- Ignored entirely — whole line only, no trailing // on other lines
Variety of box shapes
box "label"- Rectangle
rbox "label"- Rounded rectangle
bbox / rrbox "label"- Double border (box / rounded box)
diamond "label"- Decision point
text "label"- Plain label, no border
box "label" #idthe #id is optional — add it when you need to reference this shape from a connector, a group, or a mouse-driven edit.spacerorspacer:Nas the last thing on a shape's own line adds extra breathing room around just that shape; useful when printing across multiple pages.
Connectors
Connecting arrows are automatic, or for more control you can give your boxes #id values (eg #myboxid1) and use them as references
Box label 1 -> Box label 2- You can chain many simple boxes (or ids)
#A -> #B- Arrow
#A --> #B- Dashed arrow
#A ->> #B- Arrow with emphasis (e.g. urgency)
#A <-> #B- Points both ways
#A -> #B: label- Add a label to any connector (note the : after the target box!)
#A -> #B: label from:bottom to:top- Choose which edge it leaves and enters —
top/right/bottom/left— e.g. to route around another box
- Trailing tokens, any order, all optional, separated by spaces or commas:
flow:right/flow:downoverrides the diagram's default direction for just this one connector;line:elbowroutes it with a right-angle bend instead of straight;from:<edge>/to:<edge>(top/right/bottom/left) pins exactly which edge it exits/enters;spacerorspacer:Nadds extra room around it.
Shortcuts — no mouse needed
A->B->C- Quick chain — boxes are created for you
- Just type a line of text, then another. Each line becomes a box, connected in order to the one before it.
- Starting a second, separate flow? A leading
\on that line (e.g.\Alternative start) stops it inheriting a connector from whatever came before — a fresh root, not linked to the previous flow. - Want to branch off one of those lines instead of continuing straight down the list? Hit Expand (⌘E / Ctrl+E) to give every line an #id, then add a
#id -> #idconnector wherever you want a different flow.
Layout — whole diagram
flow: right- New boxes are placed left to right (default)
flow: down- New boxes are placed top to bottom
- Both are also available as a toolbar toggle — it edits this same line for you. A single connector can override this for just itself — see Connectors above.
Title and footer — whole diagram
title My Diagram, align:left- left / centre / right — defaults to centre
(center also accepted) footer: Version 1.2 — printed [date]- Export-only — never shown in the live editor
title:My Diagram(colon) also works, first one wins. Every shape shifts down to make room — nothing about their own position is changed.footeronly appears in an exported PNG/PDF, bottom-left, small and light.[date]anywhere in the text becomes today's date (d-mmm-yyyy) at export time.
Groups — a labeled subset of shapes
group "Label" #gid- Start a labeled boundary
endgroup #gid- Close it
- Everything between the two lines parses completely normally — a group is just a visual boundary drawn around them. A group's own
#idcan be used as a connector endpoint, same as any shape.
Styles — define once, whole diagram; apply per box
Use the status: keyword to define a named, reusable appearance.
status:done text:strikethrough border:grey fill:tint- Defines the 'done' appearance
box "..." #id status:done- Apply a named style to a shape
box "..." #id border:red text:italic fill:pastel- For one-off styling, just add border/text/fill instructions to a line.
border:green / blue / orange / red / grey / purple / yellow / teal / pink / indigo ("gray" also accepted).text:strikethrough / bold / italic — combine with commas, e.g.text:bold,italic.fill:none / tint / pastel — see its own section below.- A shape's own
border:/text:/fill:always wins over its status's version, property by property — set both if you want a status's look with one thing overridden. - Also settable from the inspector panel's Status field, once at least one status is defined.
Fill — wash a shape's own colour into its background
fill:tint- Diagram-wide default — subtle wash (~12%) of each shape's own border/status colour
fill:pastel- Same idea, stronger (~28%)
box "..." #id border:red fill:pastel- One shape's own
fill:overrides the diagram's default for just that shape
- Diagram-wide
fill:defaults tonone— every existing diagram looks the same until you opt in. Only ever visible on a shape that already has aborder:/status:colour; an uncoloured shape is unaffected regardless. - A shape (or its status) can set its own
fill:too — same override-wins precedent asborder:/text:, including overriding down tofill:noneon a diagram that otherwise defaults to tint/pastel.
Sequence diagram format
type: sequence starts a new one. View-only: there's no dragging or clicking to edit here; position is always computed from the text, never pinned by hand.
Comments
// a note to yourself- Ignored entirely — whole line only, same rule as flowchart
Participants — who's on the diagram
Alice->Bob: hello- A bare mention auto-creates both, in first-mention order
participant Bob- Explicit declaration — controls ordering without a message yet
participant "Web Server" #id- Quoted + #id — for a display name with spaces, and so it can be referenced by #id in messages below
#id->#id: hello- Reference a declared participant by its #id instead of retyping its full label — the only way to reference one whose label has a space in it
- Participants always render left to right in the order their name is first seen — whichever line mentions it first, declaration or message.
- A #id can be used before its own
participantline appears later in the file. One that matches no declared participant shows in red, right in the text — it's never silently turned into a new participant named "#typo".
Messages — per arrow
Alice->Bob: label- Sync — solid line, filled arrowhead
Alice-->Bob: label- Reply — dashed line, filled arrowhead
Alice->>Bob: label- Async — solid line, open arrowhead
Alice-xBob: label- Failure/lost — solid line, X instead of an arrowhead
Alice->Alice: label- Self-message — loops back to the same lifeline
: labelis always optional, same as a flowchart connector.
Activation — a lifeline bar
activate Bob- Start a bar on Bob's lifeline
deactivate Bob- End the most recently opened one
- Nesting is supported — activate twice before deactivating shows two overlaid bars, offset to the right; messages touch whichever bar is currently open, not the bare lifeline.
- An activate with no matching deactivate by the end of the diagram is closed automatically, never an error.
Notes — a labeled box beside a lifeline
note over Alice: text- Above a single lifeline
note over Alice,Bob: text- Spans every lifeline listed, in order
note left of Alice: text- Positioned to the left of one lifeline
note right of Alice: text- Positioned to the right of one lifeline
Fragments — conditional/looping/optional blocks
alt condition- First branch of an if/else-style block
else condition- Any number of else branches inside an alt
loop condition- Repeats — no else
opt condition- Optional — runs or doesn't, no else
end- Closes whichever alt/loop/opt is currently open
- The label after
alt/loop/opt/elseis free text, shown but never parsed for meaning — same as everywhere else in this format. - Fragments nest freely — a
loopinside analtbranch, for example.
Dividers, title, and footer — diagram-wide
title My Title, align:left- One per diagram — first one wins. left / centre (or center) / right
footer: Version 1.2 — printed [date]- Export-only — never shown in the live editor
==Section label==- Full-width divider with a centered label, at that point in the events
- A line that clearly attempts
note/participant/==divider==but doesn't parse (missing colon, unclosed quote, no closing==) shows in red, right in the text.
Gantt chart format
type: gantt starts a new one. View-only, same as sequence diagrams: position is always computed from each task's own dates, never dragged. Deliberately spreadsheet-simple, not a Microsoft Project clone — no dependency arrows, no critical path, no resource allocation.
Tasks — one per line
Buy milk- A bare task — shown in the list, no bar (e.g. a checklist item or heading)
Pack: st:28.sep, end:5.oct- A scheduled task — draws a bar
Wait for taxi: st:28.sep, dur:3d- A scheduled task with a duration instead of an explicit end date
- Indent a line (any consistent amount of leading whitespace) to make it a child of the task above it. Click a parent in the task list to collapse/expand its children — a viewing preference, not saved to the file. A parent's own bar is always computed from its children's dates (thinner, with flagged ends, so it reads as a rollup rather than a real task).
Project start
start:1.aug- Diagram-wide — see Year rollover below
Dates — day-before-month throughout
Business plan tasks are typically specified by dates, like these:
st:28.sep.2026- day.month.year — fully explicit
st:28.sep, dur:2d- year defaults to the current year. 2 days duration
Fiction authors might benefit from month.year type periods, like these:
st:dec.1549- month.year — resolves to the 1st of that month
st:dec.1549, dur:3m- From 1st of December for 3 months
Planning a very-fine-grained project? Use hours! Like these:
st:09:00- Time of day only — date defaults to today
Notes:
- Switch the gantt display scale between: hours/days/months/years to match your project needs.
- Month names are case-insensitive, matched on the first three letters (
sep,Sep,septemberall work).
Year rollover — for a plan crossing a year boundary
start:1.aug- Declares which month/day the diagram's own year begins on
- Once set, any other year-less date earlier in the calendar than
1.aug(e.g.10.jan) resolves to the following year — no need to write.2027on every winter-side task. A date on or after1.augstays the base year. - A date that already has an explicit year (
st:10.jan.2027) is never affected. Diagram-wide, so it works no matter where in the file it's written — same asperiod:/endcaps:.
Segments, caps, and colour — per task
st:... round, end:... squareround/square/angleshapes that specific bar's end — defaults tosquarest:A, end:A- Same start and end draws a diamond instead of a bar (ie a milestone)
st:A, end:B, st:C, end:D- Two (or more) segments on one task's row
st:A, dur:3w- Start plus a duration —
h/d/w/m/yfor hours/days/weeks/months/years — instead of an end date colour:blue- One colour per task, shared by every segment it draws
st:A, end:B, progress:60%- A percent-complete indicator drawn on that segment
colour:green / blue / orange / red / grey / purple / yellow / teal / pink / indigo ("gray" also accepted) — same fixed palette as named styles'border:.
Relative starts
Note: Only makes sense to use these with dur:xx not end:xx
st:follow, dur:5d- Starts the moment the previous dated task finishes
st:same, dur:1d- Starts alongside the previous dated task, not after it
st:follow-2d, dur:5d- 2 days before the previous task ends — offset uses h/d/w/m/y, same as dur:
st:follow+1w, dur:5d- 1 week after the previous task ends
id:Handover- Labels this task so other tasks can reference it by name
st:same(Handover), dur:1d- Starts alongside the task labelled id:Handover, wherever it is in the file
st:follow-2d(Handover), dur:1d- Offset and named reference together — offset always first
- Must be closed with
dur:, never a fixedend:— that would stop it tracking the referenced task's own slip, so it's flagged red instead. Chains cascade automatically, so if an earlier task's date changes, every task that follows it moves too.
Title, footer, period, and end-cap defaults — whole diagram
title:My Plan, align:leftleft/centre(orcenter) /right— defaults to centrefooter: Version 1.2 — printed [date]- Export-only — never shown in the live editor
period: weekshours/days/weeks/months/years— the width of each columnendcaps: st:round, end:angle- Default cap shape for any
st:/end:/dur:with no cap of its own
- Period's also available as a toolbar dropdown — it edits this same line for you. Defaults to
daysif never set. - Every row also shows a small reference number, counting from 1 — display-only, never saved to the file.
Late highlighting and the today marker
- A bar that should have started but hasn't kept pace (or finished with no progress at all) shows a red border, red label, and red progress line — a collapsed parent shows the same red if any real task underneath it is late.
- Only appears once the diagram uses
progress:somewhere — a plan with no progress tracking never shows red, since there's no real signal to flag as behind. A thin dashed line also marks today, under every bar, regardless of progress tracking.
Mind map format
type: mindmap starts a new one. View-only, same as Gantt/Sequence: position is always computed, never dragged.
The centre topic is the first line
Trip Planning- The only unindented line — everything else nests under it
Destination- Indent to make it a branch of the line above it
- A second unindented line doesn't start a second tree — it's adopted as one more branch of the centre, so nothing you write is ever lost.
Layout — radiates two-sided from the centre
layout: alternating- Main branches alternate left/right in file order — 1st right, 2nd left, 3rd right, and so on. For a brainstorm-style map with no inherent order, where visual balance matters more than reading order.
- Default (no
layout:line, orlayout: clockwise): first half of the main branches down the right (top to bottom), the rest up the left (bottom to top) — so tracing clockwise from the top visits every branch in file order. Deterministic, not a balancing algorithm. - Either way, only which side a branch lands on (and its order within that side) changes — a single branch's own children still stack directly below it, not fanned out at their own angle.
- Click a branch with children to collapse/expand it — a viewing preference, not saved to the file. It still shows its own collapse triangle while collapsed.
- A node with children draws as a bordered box; a leaf (no children) draws as plain coloured text with no box, keeping the outermost level lightweight.
- Pinch, or hold Ctrl and scroll, to zoom in and out on a large tree.
Colour — the one place this format auto-colours by default
Destination- A main branch (direct child of the centre) with no
colour:of its own gets one auto-assigned, round-robin, from the same 10-colour palette named styles use Spain: colour:blue- Explicit colour, inherited by every node under Spain unless one of them overrides it too
- Anything deeper than a main branch — a node with no
colour:of its own — always just inherits its parent's, never gets a fresh auto-assignment of its own. - A plan that never writes
colour:by hand still reads as visually distinct branches — the one deliberate exception to this format's usual "no colour unless you ask for it" rule.
Title and footer — whole diagram
title:My Plan, align:leftleft/centre(orcenter) /right— defaults to centre. Independent of the centre topic itself.footer: Version 1.2 — printed [date]- Export-only — never shown in the live editor
- A malformed
colour:token (wrong delimiter or an unrecognized name) shows in red, right in the text.
Swimlane format
type: swimlane starts a new one. View-only, same as Gantt/Mind map: position is always computed, never dragged.
Lanes
lane Customer- Every step after this line belongs to the Customer lane, until the next
laneline lane Sales: colour:blue- Tints the lane's band and header — same 10-colour palette as
border:
- Writing the same lane name again reopens that lane — no duplicate band — so the text can follow the process as it hands back and forth.
- Lanes draw in order of first appearance. Indenting steps under a lane is just for readability — membership comes from the last
laneline.
Steps — per step
Place order- A bare line is a plain box
In stock?: diamond, #stock- Label, then a colon, then comma-separated attributes, any order
rbox/bbox/rrbox/diamond/circle/text- Same shape keywords as flowchart —
bbox/rrboxare double-bordered border:green, fill:pastel- Same styling as flowchart:
border:,fill:none|tint|pastel,text:bold, italic,status:<name> status:done border:grey text:strikethrough- A top-level named style, used by any step with
status:done
- A step's label is everything before its first colon, so a label can't contain one.
- A malformed attribute (
border=green,border:mauve) shows in red, right in the text.
Connections — per connector
- Each step connects from the one before it in the file automatically — including across lanes, which is the hand-off a swimlane exists to show.
#stock -> #pick: yes- Branch explicitly — same arrows and
: labelas flowchart #stock -> Place order: no- Endpoints can be an
#idor a step's own label #ce -> #design: no, from:bottom, to:bottom- Pick the edges a connector leaves and enters —
top/right/bottom/left— e.g. to stop it crossing another line \Second start- A leading
\stops this step connecting from the one before it
- An explicit connector from an earlier step replaces that step's automatic connection; a loop back from a later step is added alongside it instead.
from:andto:go after the label (or on their own, with no label). Name just one and the other end stays automatic. Routes aren't checked for crossings — the edges you name are the route you get.
Layout, title and footer — whole diagram
flow: down- Lanes become columns running top to bottom — default is
right(lanes as rows) fill: tint- Diagram-wide fill default, same as flowchart
title:My Process, align:leftleft/centre(orcenter) /right— defaults to centrefooter: Version 1.2 — printed [date]- Export-only — never shown in the live editor
- Each step sits one place along from the furthest step leading into it, so a branch's two arms sit side by side. Connectors are always drawn with right-angle bends.
- Click a step or lane name to jump to its line in the text.