How DGMO Thinks
A guide to the design principles behind the DGMO language. Understanding these themes will help you write diagrams faster and make better use of the language’s features.
New to the vocabulary? The Glossary defines the words the chart-type guides use — directive, metadata, tag group, alias, leaf, and the rest.
What a Clean Check Does and Doesn’t Tell You
When the editor reports no problems, it is telling you one thing: the file could be read. It is not telling you the diagram is right.
DGMO is deliberately forgiving. Rather than reject a line it does not recognise, it usually finds some reading for it — a stray word becomes part of a label, an unfamiliar setting becomes a data row. That forgiveness is what lets you type freely without fighting the parser. The cost is that a mistake often produces a diagram rather than an error.
Here is what that looks like in practice.
A label can absorb your data. Type an accidental space inside a number:
bar Doubloons by Month
Jan 42
Feb 5 8
Mar 71No errors. But the middle bar is now labeled “Feb 5” with a value of 8, not 58. The chart is drawn, the axis has quietly rescaled, and nothing is flagged.
A mistyped setting becomes content. Directives are ordinary words on ordinary lines, so a typo in one does not look like a typo:
bar Doubloons by Month
wibble-wobble 4
Jan 42No errors — and a bar called “wibble-wobble” is now sitting in your chart. Note the shape of this trap: it is the number that does it. A misspelling on its own (wibblewobble) is caught and reported; a misspelling followed by a value looks exactly like a data row, so it becomes one. Count your bars.
Dates can end up somewhere other than where you meant. A gantt task takes its duration from the last word on the line, and everything before that becomes the name:
gantt Voyage to Tortuga
Provision Ship 2026-01-05 4dNo errors. But the task is now named “Provision Ship 2026-01-05”, and nothing has told the chart when the voyage begins. Give the plan its start date once, on a start-date line at the top, and every task schedules from it — here with crew tags, progress, dependencies and a sail-day marker:
gantt Voyage to Tortuga
start-date 2026-01-05
tag Crew as c
Officers red
Hands blue
Shipwright orange
marker 2026-01-14 Sail Day green
[In Port]
Provision Ship 4d c: Hands, progress: 100
-> Load Cannons 2d c: Hands, progress: 60
Repair Hull 6d c: Shipwright, progress: 80
Recruit Crew 5d c: Officers, progress: 40
-> Sign Articles 1d c: Officers
+9d [At Sea]
Cross the Caribbean 8d c: Hands
-> Make Landfall 0dNumbers get normalised without comment. Percentages in a pie chart are recalculated from whatever you supply, so three values of 30 each display as 33%. If you expected them to add up to 100 and they don’t, the chart will not say so.
What to check instead
A clean check is the floor, not the finish line. After any edit, spend ten seconds on the picture:
- Read the labels. If one has a number stuck to it, a value has been swallowed.
- Look at the axis. Does its range match the numbers you believe you entered? A rescaled axis is the fastest sign that a value was misread.
- Count the items. Are there more shapes than you wrote, or fewer? An extra one usually means a directive or a stray line became content.
- Check the totals. Add up the values you meant to enter and compare them against what the chart reports.
- Check the span. On anything time-based, confirm the first and last dates are the ones you intended, and that the overall length is what you asked for.
- Read the warnings, not only the errors. A warning means something was drawn but probably not what you meant — an item with no value, a number that was ignored, a setting that does not apply. Warnings catch several of these cases; the mistakes above are the ones that slip past even those.
The rule of thumb: a clean check means “I understood you.” Only the render can tell you whether it understood you correctly.
Indent, Don’t Repeat
The most important pattern in DGMO: write the thing once, then indent what belongs to it beneath.
Instead of repeating the source on every line:
// Verbose — repeats "API" three times
API -routes-> UserService
API -routes-> ProductService
API -auth-> AuthServiceIndent edges under their source:
// Concise — declare once, indent connections
API
-routes-> UserService
-routes-> ProductService
-auth-> AuthServiceThis isn’t just a shorthand — it’s how DGMO thinks about ownership and hierarchy. The pattern shows up everywhere:
- Org charts and sitemaps — indentation is the hierarchy
- Kanban — cards indented under columns
- Gantt — dependencies indented under tasks
- ER — columns and relationships indented under tables
- Sequence — participants indented under groups
When you see indentation in DGMO, read it as “belongs to.”
How Indentation Works
Every guide on this site shows you indented examples. None of them tell you the rules. Here they are, each drawn with its source open beneath it.
How many spaces?
Any number, as long as you are consistent. DGMO counts steps, not spaces. It looks at each line and asks “is this deeper, shallower, or the same as the line above?” — never “how many spaces is this?”
These three files differ only in their indentation:
// two spaces
Gold
Doubloons
Ingots
Gems
Rubies
Pearls// four spaces
Gold
Doubloons
Ingots
Gems
Rubies
Pearls// one space
Gold
Doubloons
Ingots
Gems
Rubies
PearlsAll three draw exactly the same mind map:
Two spaces per level is the convention used throughout these guides, and it is what the app writes. There is nothing special about the number two — pick a step size and stay with it.
Because only the steps count, you cannot indent “half a level.” Going from no indent to four spaces in one jump is one step deeper, exactly the same as going to two spaces. There is no way to land between levels.
Do tabs work?
Yes. A file indented entirely with tabs draws the same chart as a file indented entirely with spaces.
But do not mix tabs and spaces in the same file. A tab counts as four columns. In the file below, every line uses two spaces except Pearls, which starts with one tab. This page draws the tab wide, so you can see it. An editor set to two-space tabs would line it up exactly with Rubies. To DGMO it is two steps deep, so Pearls becomes a child of Rubies — and nothing warns you:
This is the one indentation mistake that silently changes your diagram. Most editors draw a tab and four spaces identically, which is exactly why it bites. If a line lands in the wrong place and the file looks correct, suspect a stray tab.
What does a deeper indent mean?
This is the part worth reading twice: a deeper indent means different things depending on what is on the line. DGMO looks at the shape of the indented line to decide. There are four shapes.
1. A plain name is a child
The indented thing belongs to the thing above, and the hierarchy is the diagram:
Anne Bonny and Calico Jack report to Blackbeard; Mary Read reports to Anne. This is how org, sitemap, mindmap, treemap, family, and C4 read indentation.
2. An arrow starts from the line above
A line that opens with an arrow is a connection, and it leaves from the line above it:
All three routes leave Nassau. Tortuga, Port Royal and Lisbon are not children of Nassau — they are separate places, drawn beside it and joined to it by lines. Writing Nassau -rum-> Tortuga on three separate lines draws the same thing; indenting saves you repeating the name.
Chart types that read indented arrows this way: boxes-and-lines, infra, flowchart, C4, ER, class, sitemap, gantt, PERT, swimlane, cycle, and map routes.
3. key: value is a fact about the line above
A line with a colon adds a detail to the thing above it rather than adding a new thing. Here the fact is a rank, and the rank decides the colour:
r: Captain does not add a crew member called “r” — the colon tells DGMO this is a detail about Blackbeard. The second r: sits one step deeper, under Anne Bonny, because it belongs to her.
That depth is the thing to watch. Put r: Mate at the same depth as Anne Bonny and it no longer belongs to her. The file still reads fine, but the ranks land on the wrong people:
4. Under a bracket line is inside the group
A name in square brackets is a container, and everything indented beneath it goes inside:
Each card sits in the column it is indented under. The same rule puts nodes inside a [Group] on boxes-and-lines and infra, and participants inside a box on a sequence diagram.
So one indent step can mean “is a child of,” “starts an arrow from,” “is a fact about,” or “goes inside.” The chart-type guide for whatever you are drawing tells you which of these it uses.
Things that do not matter
- Blank lines. You can leave a blank line in the middle of an indented block to space things out. It does not end the block.
- Trailing spaces at the end of a line.
- Indenting a comment. A
//line can sit at any depth. - Indentation in flat data charts. A bar or pie chart is a list, not a tree, so indenting its rows changes nothing. It also gains you nothing.
Meaning First, Color Second
When you want to make something red, your instinct might be to reach for a trailing color: AuthService red. That works for one-offs. But DGMO encourages a different approach for anything that carries meaning.
Tags let you separate what something means from how it looks:
tag Priority as p
Critical red
Normal green
Low gray
API p: Critical
Cache p: LowWhy go through this indirection?
- Colors become meaningful. Red means “Critical,” not just red. The legend self-documents.
- Palettes stay intact. Switching from Nord to Atlas adjusts all your colors harmoniously. Direct hex codes would break this.
- Filtering works. Tags are structured metadata — you can sort, hide, and group by them.
- One change updates everything. Rename “Critical” to “Urgent” in one place, not fifty nodes.
Use trailing color names (red, blue, …) for quick visual accents. Use tags when color carries meaning you’d want in a legend.
Name Things, Skip the Boilerplate
DGMO infers as much as it can from names you’re already writing.
In sequence diagrams, the parser recognizes common names and gives them the right shape automatically:
Redis // cache (cylinder, dashed)
Kafka // queue (horizontal cylinder)
User // actor (stick figure)
PostgresDB // database (cylinder)You only need is a when the name doesn’t match a pattern:
Vault is a database // "Vault" matches no rule, but you want database
Notifications is a queue // "Notifications" matches no ruleThe first declared tag group auto-activates. Chart types are detected from the first line. Org hierarchy comes from indentation alone.
The principle: name things sensibly and DGMO figures out the rest. Override only when inference gets it wrong.
Palette-Aware Colors
When you write red, DGMO doesn’t render #ff0000. It renders the red from your active palette — a shade that harmonizes with the other ten named colors in that palette.
The allowed color names are: red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white.
That’s the complete list of colors an element can take. No hex codes, no CSS keywords, no twelfth name. This is a deliberate constraint:
- Every palette (Nord, Catppuccin, Atlas, Tokyo Night, etc.) defines its own version of these eleven names
- Switching palettes recolors your entire diagram coherently
- Diagrams always look good regardless of which palette or theme is active
- No one accidentally picks colors that clash or become invisible on certain backgrounds
The palette itself is not locked. A file can name a built-in palette with a palette line, such as palette nord at the bottom of the file. It can also carry a custom palette: a palette block that gives the eleven names hex values of your own. That block is the one place DGMO accepts hex. An override where the diagram is drawn, such as --palette on the command line, still beats the file’s line. Colors & Palettes has the details.
DGMO prioritizes beautiful by default over total control.
Brackets Mean “Container”
Wherever you see [Name], something is being grouped:
[Backend] // group in infra, boxes-and-lines, C4
[To Do] // column in kanban
[Sprint 1] // swimlane in gantt
[Marketing] // container in sitemap
[Caribbean] // category in scatter charts
[Royal Navy] // group in timelineContent indented below the bracket line belongs to that group. Bracket grouping works in sequence, infra, flowchart, state, org, kanban, sitemap, gantt, boxes-and-lines, timeline, and scatter/bubble diagrams. When you see brackets, read them as “these things go together.”
Groups carry metadata after the closing bracket. When color rides alongside other keys, use the long form color: <name>:
[Backend] color: blue, team: Platform
API
Database
CacheFor semantic coloring, lean on tag aliases — [Backend] t: Platform (where t is a declared tag alias) lets the legend drive the fill instead of hardcoding the swatch. Kanban columns and pyramid/ring phase headers are the only groups that accept a bare trailing color ([Done] green); elsewhere, use the color: key.
One Arrow Vocabulary
DGMO uses the same small set of arrow patterns everywhere:
| Pattern | Meaning | Example |
|---|---|---|
-> | Synchronous / directed | API -> Database |
~> | Asynchronous | API ~> Queue |
-label-> | Labeled edge | -routes-> UserService |
~label~> | Labeled async edge | ~notify~> Email |
<-> | Bidirectional | A <-> B |
The label goes between the dashes (or tildes). -> and -label-> work in every chart that has edges — sequence, infra, flowchart, C4, ER, class, sitemap, boxes-and-lines, and more. The async forms (~>, ~label~>) belong to the charts where a message can be sent without waiting, such as sequence, infra and C4. Flowchart does not take them. On a map route, ~> draws an arc instead of a straight leg. Bidirectional arrows (<->, <~>, and the labeled <-label->) are a boxes-and-lines convenience. There is no left-pointing arrow: write B -> A, not A <- B.
Learn the shape once, then reach for the variant the diagram type allows.
Metadata: The Universal “And Also…”
When you need to attach extra information to something, the same key: value syntax works on almost anything:
API description: Main gateway, team: Platform
API -routes-> UserService frequency: High
[Backend] owner: Platform Team
Database Schema 10bd p: Foundation, progress: 80
1718-05 Blockade p: Blackbeard
Card Title priority: High, assignee: AliceNodes, edges, groups, tasks, events, cards — if it exists in DGMO, you can probably attach metadata to it. The format is always key: value, key2: value2 trailing the name, or indented key: value lines beneath it.
Describe Relationships, Not Layouts
DGMO diagrams have no x/y coordinates, no manual positioning, no pixel-level control. You describe what things are and how they connect, and the layout engine handles placement.
// You write this
CEO
CTO
Engineering
DevOps
CFO
Finance
// DGMO handles the layoutThis is a trade-off:
- Diagrams reflow cleanly when content changes — add a node and everything adjusts
- Version control diffs are meaningful (text changes, not coordinate noise)
- You spend time on content, not dragging boxes around
- But you don’t get pixel-perfect placement
If you find yourself wanting to control exact positions, you’re probably fighting the tool. Instead, use groups, ordering, and direction options (direction-tb, direction-lr) to guide the layout.
Directives Are Simple Toggles
Configuration goes at the top of the diagram as plain keywords. The chart-type guides call these lines directives; this page has historically called them options. They are the same thing — if you have learned one word you already know the other.
gantt Product Launch
start-date 2026-03-15
today-marker
critical-path
no-dependencies
active-tag Team- Boolean options: bare keyword turns it on,
no-prefix turns it off (activations/no-activations) - Value options: keyword followed by the value, space-separated (
start-date 2026-03-15) - No YAML, no JSON, no nested config blocks
- Options must appear before diagram content. The one exception is the
paletteline, which usually sits at the bottom of the file (see Colors & Palettes) - A few toggles are universal — every chart that renders the corresponding surface accepts them.
no-legendhides the legend (data charts included),no-titledrops the banner title, andno-valuesuppresses per-item value labels.
The Colon Rule
Colons show up in exactly two situations:
1. Open-ended metadata — when you’re defining freeform key-value pairs:
API description: Main gateway // same-line metadata
role: Senior Engineer // org/C4 indented metadata2. Type separators — where both sides can contain spaces and a delimiter is needed:
+ name: string // class field type
+ sail(): void // class method return
Trajectory blue: -0.001*x^2 + 0.27*x // function expressionNo colons anywhere else — declarations, options, tags, data rows, arrows, groups, and comments are all colon-free:
bar Revenue by Quarter // declaration: no colon
tag Team as t // tag: no colon
start-date 2026-03-15 // option: no colon
Gold 3500 4200 5100 // data row: no colon
id int pk // ER column: no colon
default-rps 100 // infra option: no colonThe intuition: if DGMO already knows what the fields are, spaces are enough. Colons appear only when you’re defining something freeform or need an unambiguous separator.
One Diagram Per File
The first line declares the chart type. There’s no way to embed multiple diagrams in a single file. One file, one diagram, one clear purpose.
sequence Auth Flow
// everything below is this one diagramComments Are Full-Line Only
// This is a comment
API -> Database // This is NOT a comment — it's part of the lineUse // at the start of a line. There are no inline comments, and # is not a comment character. The one exception is PERT, which also accepts #, and a comment at the end of a line.