If you've ever tried to create a flowchart using plain text instead of dragging boxes on a canvas, you've already encountered diagram codes. These text-based syntax systems let you define shapes, connections, and logic using short lines of code no mouse required. A solid syntax reference for flowcharts saves you from guessing the right keywords, formatting rules, and connection types every time you start a new diagram. Whether you're documenting a process in a README file or mapping out decision logic in a planning doc, knowing the exact syntax rules makes the difference between a chart that renders correctly and one that breaks.

What are diagram codes for flowcharts?

Diagram codes are text-based markup languages that let you describe a flowchart's structure using words and symbols instead of visual editors. Tools like Mermaid, PlantUML, Graphviz (DOT language), and D2 read these codes and render them as visual diagrams. Each tool has its own syntax rules, but the core idea is the same: you write out nodes, connections, and flow directions using a specific shorthand, and the tool turns that into a graphic.

For example, in Mermaid syntax, a simple flowchart might look like this:

graph TD
  A[Start] --> B{Is it valid?}
  B -->|Yes| C[Process]
  B -->|No| D[Reject]

That single block of text produces a top-down flowchart with a start node, a decision diamond, and two outcomes. The syntax defines the shape type (rectangles, diamonds), the labels, and the arrows between them.

Why do people use text-based flowchart syntax instead of drag-and-drop tools?

There are practical reasons developers, technical writers, and project managers prefer code-based diagrams:

• Version control friendly Text files work with Git. You can track changes, review diffs, and collaborate on diagrams the same way you do with code.
• Faster for simple diagrams Typing a short syntax block is often faster than opening a visual tool, placing boxes, and drawing arrows by hand.
• Embeddable in documentation Many platforms (GitHub, GitLab, Notion, Obsidian, Confluence) render Mermaid or similar syntax directly in markdown files.
• Consistent output The tool handles layout, spacing, and styling every time, removing human inconsistency from the visual result.
• Easy to update Changing a label or adding a step means editing one line of text, not redrawing a section of a diagram.

If you're comparing this approach to keyboard shortcuts in visual editors, there's a meaningful difference in workflow we break that down in our article on diagram codes vs. diagram shortcuts.

How does Mermaid flowchart syntax work?

Mermaid is one of the most widely used diagram code languages. It's built into GitHub, GitLab, Notion, and many documentation tools. Here's a quick syntax reference for flowcharts:

Declaring the chart direction

Every Mermaid flowchart starts with a direction keyword:

• graph TD top-down (most common for process flows)
• graph LR left to right (useful for timelines or swimlane-style flows)
• graph BT bottom to top
• graph RL right to left

Defining nodes and shapes

Nodes are defined by their ID and the bracket style wrapping the label:

• A[Text] rectangle (process step)
• A(Text) rounded rectangle (start/end terminal)
• A{Text} diamond (decision point)
• A((Text)) circle
• A>Text] flag/asymmetric shape
• A[[Text]] subroutine (double-bordered rectangle)

Connecting nodes

Arrows define the flow between nodes:

• A --> B solid arrow
• A --- B solid line, no arrowhead
• A -.-> B dotted arrow
• A ==> B thick arrow
• A -->|Label| B arrow with a text label on the connection

Subgraphs for grouping

You can group related nodes inside a labeled section:

subgraph Validation
  X[Check input] --> Y{Valid?}
  Y -->|No| Z[Return error]
end

This is useful for showing phases, departments, or system boundaries within a larger flow.

How does PlantUML flowchart syntax compare?

PlantUML uses a different structure but covers similar ground. Here's how the same decision flow looks in PlantUML:

@startuml
start
:Start;
if (Is it valid?) then (yes)
  :Process;
else (no)
  :Reject;
endif
stop
@enduml

PlantUML uses a more imperative style you describe actions in sequence with colons and use if/else/endif for decisions. It's closer to pseudocode than Mermaid's declarative node-link approach.

Key PlantUML syntax elements for flowcharts:

• :Action; defines a process step
• if (condition) then (yes-path) else (no-path) endif decision branching
• start and stop terminal points
• :>Arrow label label on a connection
• partition "Name" { } groups steps under a section header

How does Graphviz DOT syntax work for flowcharts?

Graphviz uses the DOT language, which is more low-level. You define nodes and edges explicitly, and the layout engine decides positioning:

digraph flowchart {
  rankdir=TD;
  A [label="Start" shape=box];
  B [label="Is it valid?" shape=diamond];
  C [label="Process" shape=box];
  D [label="Reject" shape=box];
  A -> B;
  B -> C [label="Yes"];
  B -> D [label="No"];
}

DOT gives you fine-grained control over node attributes (shape, color, font), edge properties (style, label, weight), and graph-level settings (direction, rank). It's more verbose but very flexible.

Which flowchart syntax should you choose?

Your choice depends on where you'll use the diagram and how complex it is:

• Mermaid Best for documentation embedded in GitHub, GitLab, Notion, or markdown. Low learning curve. Good enough for most process flows.
• PlantUML Better for complex logic with nested conditions. Strong support for software design flows. Requires a rendering engine or plugin.
• Graphviz (DOT) Best when you need precise layout control or have large, complex graphs. Steeper syntax but very powerful.
• D2 A newer option with clean syntax and modern rendering. Growing ecosystem.

If you're evaluating tools for generating these diagrams automatically, our UML diagram code generator tool comparison covers several options side by side.

What are the most common flowchart syntax mistakes?

Even experienced users hit these issues regularly:

1. Mismatched bracket types Using [] when you meant {} changes the shape entirely. A rectangle instead of a diamond breaks the visual meaning of a decision point.
2. Missing arrow direction Forgetting --> and writing -- creates a line without an arrowhead, which can confuse readers about the flow direction.
3. Unquoted special characters Labels with colons, pipes, or brackets need quotes in some syntaxes. A["Step: Process"] works, but A[Step: Process] may break.
4. Undefined node references Connecting a node ID that was never defined. In Mermaid, implicit definitions work, but in DOT you must declare nodes before referencing them.
5. Forgetting the direction declaration Mermaid requires graph TD or graph LR at the start. Without it, nothing renders.
6. Indentation errors in subgraphs The end keyword must be on its own line and at the correct nesting level.

For a deeper look at reading and interpreting these codes across different tools, see our guide on how to read diagram codes in architecture software.

What are practical tips for writing cleaner flowchart code?

These habits make your diagram code easier to maintain and debug:

• Use descriptive node IDs validate_input is clearer than B when you revisit the code later. Labels can be short; IDs should be meaningful.
• Add comments In Mermaid, use %% This is a comment. In DOT, use // or / /. Comments help teammates understand your intent.
• Group related nodes into subgraphs This improves readability and helps the layout engine place related elements closer together.
• Test incrementally Don't write 50 lines and then render. Add 3–4 nodes, check the output, then keep building. This catches syntax errors early.
• Use label text on connections, not just nodes Decision paths are clearer when the arrow itself says "Yes" or "No" instead of relying on node position alone.
• Keep one decision per diamond Avoid combining multiple conditions in a single decision node. Split them into separate steps for clarity.

Quick reference: shape syntax comparison across tools

Shape	Mermaid	PlantUML	Graphviz DOT
Rectangle (process)	A[Text]	:Text;	shape=box
Rounded rectangle (terminal)	A(Text)	start/stop	shape=box style=rounded
Diamond (decision)	A{Text}	if (Text) then	shape=diamond
Circle	A((Text))	circle	shape=circle
Parallelogram (I/O)	A[/Text/]	input/output	shape=parallelogram

Practical next step: your flowchart syntax checklist

Use this checklist before you share or commit any flowchart code:

1. Did you declare the chart direction at the top?
2. Are all bracket types correct for each intended shape?
3. Do decision nodes use diamonds and process nodes use rectangles?
4. Are all arrows pointing in the right direction with --> (not --)?
5. Are labels on decision branches (Yes/No) placed on the connection arrows?
6. Are special characters in labels properly quoted?
7. Did you render and visually verify the output before committing?
8. Did you add comments explaining non-obvious logic?
9. Are subgraph blocks properly opened and closed?
10. Would someone unfamiliar with this diagram understand the flow by reading the code?

Print this list or save it alongside your diagram files. The ten seconds it takes to check these items will save you from broken renders and confusing diagrams down the line. If you're ready to go further, try rewriting an existing flowchart from a visual tool into Mermaid or PlantUML syntax it's the fastest way to internalize the rules and build real fluency with diagram code.