Flowchart Code Syntax Reference Guide

If you've ever needed to turn a messy process into a clear visual, you already know why flowcharts matter. But drawing them by hand or dragging boxes in a GUI gets old fast especially when you need to update, share, or version-control a diagram. That's where writing flowcharts in code comes in. A solid flowchart code syntax reference guide gives you the building blocks to create diagrams from plain text, using tools like Mermaid, PlantUML, and similar diagram-as-code platforms. This guide walks you through the core syntax, real examples, and the mistakes that trip people up.

What does "flowchart code syntax" actually mean?

Flowchart code syntax is a text-based markup language used to define flowchart diagrams. Instead of dragging and dropping shapes in a visual editor, you write structured code that describes each node, connection, and decision in your flow. A tool then reads that code and renders the diagram for you.

Different tools have slightly different syntax rules, but the core idea is the same: you define a start node, add process blocks, insert decision diamonds for conditional logic, and connect them with directional arrows. The result looks the same as a hand-drawn flowchart it's just built from text.

Who uses flowchart code syntax, and why?

Developers and technical writers use code-based flowcharts for a few practical reasons:

Version control. Since the diagram is text, it lives in Git alongside your code. You can diff changes, review pull requests, and track edits over time.
Speed. Once you know the syntax, writing a flowchart in code is faster than opening a diagramming tool and arranging boxes manually.
Consistency. Templates and reusable snippets keep your team's diagrams looking uniform.
Integration. Many documentation platforms including GitHub, GitLab, Notion, and various static site generators render flowchart code directly in markdown files.

If you're documenting a software architecture, mapping a user journey, or explaining a troubleshooting process, text-based flowcharts keep things clean and maintainable.

What are the core syntax elements every flowchart needs?

Regardless of the tool you use, most flowchart code shares these fundamental building blocks:

Nodes (shapes)

A node represents a step or state in your process. Different shapes carry different meanings rectangles for processes, rounded rectangles or stadium shapes for start/end terminals, diamonds for decisions, and parallelograms for input/output. In most text-based syntax, you define a node with an identifier and a label.

Connections (arrows)

Arrows define the flow between nodes. You typically specify a source node, an arrow type (solid, dotted, thick), and a destination node. Some syntaxes let you add labels to arrows to describe conditions, like "Yes" or "No" on a decision branch.

Direction

Most tools let you set the overall flow direction top to bottom (the default), left to right, or others. This affects how the rendered diagram is laid out.

Subgraphs and grouping

For complex flows, you can group related nodes into labeled sections called subgraphs. This is useful for separating phases of a process or highlighting a subsystem within a larger diagram.

How does the syntax differ between Mermaid and PlantUML?

The two most popular text-based flowchart tools are Mermaid and PlantUML. Both achieve the same result but use different syntax styles.

In Mermaid, you start a flowchart block with the flowchart keyword (or the older graph keyword), declare the direction, then list nodes and connections. Mermaid uses short codes for shape types for example, {} for diamonds, () for rounded shapes, and [] for rectangles.

If you're new to Mermaid, our Mermaid flowchart syntax examples for beginners cover the basics with working code you can paste directly into a renderer.

In PlantUML, you use keywords like start, stop, if, then, and else to structure the flow. PlantUML's syntax reads almost like pseudocode, which some people find easier to follow. For a step-by-step breakdown, see how to write flowchart code in PlantUML.

Our full flowchart code syntax reference covers both tools side by side, including shape notation, theming, and advanced features.

Can you show a simple example in each tool?

Here's a basic flowchart that models a login process first in Mermaid, then in PlantUML.

Mermaid example

flowchart TD
 A[Enter credentials] --> B{Valid?}
 B -- Yes --> C[Grant access]
 B -- No --> D[Show error]
 D --> A

PlantUML example

@startuml
start
:Enter credentials;
if (Valid?) then (yes)
 :Grant access;
else (no)
 :Show error;
endif
stop
@enduml

Both produce the same logical flow. The Mermaid version uses a more declarative style, while PlantUML reads more like structured pseudocode.

What common mistakes should you watch out for?

After working with flowchart code across multiple projects, here are the errors that come up most often:

Forgetting the direction keyword. In Mermaid, if you skip TD or LR, the renderer may default to an unexpected layout or throw an error.
Mismatched shape delimiters. Opening a node with [ but closing with ) won't render correctly. Keep your brackets paired.
Using spaces in node IDs. Most tools expect single-word identifiers. Use underscores or camelCase instead of spaces in IDs (labels can have spaces).
Duplicate node IDs with different labels. If you define the same ID twice with different text, the last definition wins and your diagram may look wrong without any error message.
Missing arrow syntax on decision branches. In PlantUML, forgetting the then or else keyword inside an if block breaks the structure. In Mermaid, unlabeled decision arrows can confuse readers.
No rendering preview during editing. Write your code in an environment that shows a live preview. Catching syntax issues early saves time.

How do you pick the right tool for your project?

There's no single "best" syntax. The right choice depends on your context:

Use Mermaid if your platform already supports it (GitHub, GitLab, Obsidian, Notion). It requires zero setup and renders natively in markdown.
Use PlantUML if you need more diagram types beyond flowcharts sequence diagrams, class diagrams, state diagrams and want one tool for everything.
Use D2 or Graphviz if you need fine-grained control over layout and styling, or if your flowchart is unusually large or complex.

Five practical tips for writing better flowchart code

Start with a rough outline on paper. Sketch the flow before writing code. Knowing your nodes and branches upfront prevents mid-code rewrites.
Use meaningful node IDs. Instead of A, B, C, use login_input, validate, dashboard. It makes the code readable and easier to maintain.
Keep decision paths clear. Always label your "Yes/No" or "True/False" branches. Unlabeled arrows force readers to guess the logic.
Test with your actual renderer. Different Mermaid versions handle edge cases differently. Always preview with the specific renderer your audience will use.
Version your diagrams like code. Store flowchart files in your repository with meaningful commit messages. Treat diagram changes with the same care as code changes.

Quick checklist before you publish a flowchart

☑ Every decision node has labeled branches (Yes/No, pass/fail, or specific conditions)
☑ Start and end points are clearly marked
☑ Node IDs are unique and descriptive
☑ Brackets and delimiters are correctly paired
☑ Direction keyword is set (TD, LR, etc.)
☑ The diagram renders without errors in your target platform
☑ Labels are short enough to fit inside shapes without overflow
☑ The flow reads top-to-bottom or left-to-right without confusing crossings

Run through this list before committing your flowchart code. It takes two minutes and prevents the most common rendering and readability issues.