Understanding Diagram Code Syntax for Flowcharts and Sequences

If you've ever spent too long dragging boxes and arrows around in a diagramming tool, you already understand the appeal of diagram codes. Instead of clicking through menus, you write a few lines of text and get a polished flowchart or sequence diagram. Learning the diagram codes syntax for flowcharts and sequence diagrams saves time, keeps diagrams consistent, and makes version control possible. This guide breaks down exactly how these text-based notations work, with real examples you can copy and use right away.

Before diving in, it helps to understand what diagram codes mean in diagramming software and how they fit into the broader diagramming ecosystem.

What is diagram code syntax for flowcharts and sequence diagrams?

Diagram code syntax is a plain-text markup language that describes the structure of a diagram. You write human-readable instructions nodes, connections, participants, messages and a rendering engine turns those instructions into a visual chart. Two of the most common diagram types supported this way are flowcharts (showing process steps and decisions) and sequence diagrams (showing interactions between actors or objects over time).

Several tools use this approach. Mermaid, PlantUML, and WebSequenceDiagrams each have their own syntax rules, but the core idea is the same: describe your diagram in text, let the tool render it.

How does flowchart syntax work?

Mermaid flowchart syntax

Mermaid is one of the most widely adopted diagram code languages. It works inside GitHub, GitLab, Notion, Obsidian, and many documentation tools. Here's a basic flowchart:

flowchart TD A[Start] --> B{Is it working?} B -->|Yes| C[Deploy] B -->|No| D[Fix the bug] D --> B

Let's break that down:

flowchart TD declares a top-down flowchart. You can also use LR (left to right), BT (bottom to top), or RL.
A[Start] creates a node with the label "Start." Square brackets produce a rectangle (process step).
B{Is it working?} uses curly braces to create a diamond shape (decision node).
--> draws a directed arrow between nodes.
|Yes| adds a label to the arrow.
The last line connects node D back to B, creating a loop.

Mermaid node shapes you'll actually use

[text] Rectangle (process)
{text} Diamond (decision)
(text) Rounded rectangle (start/end)
[/text/] Parallelogram (input/output)
[[text]] Subroutine shape
((text)) Circle
{/text/} Hexagon (preparation)

PlantUML flowchart (activity diagram) syntax

PlantUML handles flowcharts through its activity diagram syntax. The approach is different from Mermaid you describe actions and conditions sequentially:

@startuml start :Start the process; if (Is it working?) then (yes) :Deploy; else (no) :Fix the bug; stop endif stop @enduml

In PlantUML, colons and semicolons wrap action labels, and if/else/endif blocks handle decisions. The syntax reads more like pseudocode than a graph definition.

How does sequence diagram syntax work?

Mermaid sequence diagram syntax

Sequence diagrams show how different participants exchange messages over time. Here's a simple example in Mermaid:

sequenceDiagram participant User participant Server participant Database User->>Server: Login request Server->>Database: Query user Database-->>Server: User data Server-->>User: Login success

Key syntax rules:

sequenceDiagram declares the diagram type.
participant defines each actor or system. You can also add aliases: participant U as User.
->> draws a solid arrow with an open head (synchronous message).
-->> draws a dashed arrow with an open head (return/response message).
-> draws a solid arrow with a closed head (asynchronous message).

Adding loops, alt blocks, and notes

Real sequence diagrams often need more than simple arrows. Mermaid supports these blocks:

loop wraps a repeated interaction: loop Every 5 minutes
alt/else conditional branches: alt Success ... else Failure
opt optional interactions: opt User is admin
note adds annotations: note right of Server: Validate token
rect highlights a section with a background color: rect rgb(200, 220, 255)

Here's a more realistic example:

sequenceDiagram participant C as Client participant S as Server participant DB as Database C->>S: POST /login S->>DB: SELECT user WHERE email = ? alt User found DB-->>S: User record S-->>C: 200 OK + JWT else User not found DB-->>S: null S-->>C: 401 Unauthorized end

PlantUML sequence diagram syntax

PlantUML uses a similar structure but with slightly different syntax:

@startuml actor User participant "Auth Service" as Auth database "User DB" as DB User -> Auth: POST /login Auth -> DB: Query credentials DB --> Auth: User found Auth --> User: JWT token @enduml

PlantUML also supports alt, loop, opt, group, and ref blocks for more complex interactions. It uses activate and deactivate to show the lifeline of a participant being processing.

When should you use diagram codes instead of a visual editor?

Text-based diagram code isn't always the right choice. Here's when it works best:

Documentation in code repositories Diagram codes live in Markdown files and render automatically on GitHub and GitLab. No need for separate image files.
Version control Text diffs show exactly what changed in a diagram. Binary image files don't offer that.
Quick prototyping When you need to sketch a process fast without fiddling with layout, typing a few lines is faster than dragging shapes.
Consistency across a team Everyone uses the same syntax rules, reducing style drift in documentation.
Automated documentation CI/CD pipelines can generate diagrams from code comments or configuration files automatically.

A visual editor still makes sense when you need precise pixel-level layout control, complex custom styling, or presentations for non-technical stakeholders.

What are the most common mistakes people make with diagram code syntax?

Forgetting indentation in Mermaid

Mermaid relies on indentation to nest elements inside blocks like alt or loop. If your diagram won't render, check your spacing first. Two spaces is the standard indent.

Using special characters without escaping

Characters like parentheses, quotes, and ampersands inside labels can break the parser. In Mermaid, wrap labels in quotes if they contain special characters: A["Step (draft)"].

Confusing arrow types in sequence diagrams

Using --> (dashed) when you mean ->> (solid) changes the meaning of your diagram. Solid arrows represent synchronous calls; dashed arrows represent responses. Mixing them up confuses readers who know UML conventions.

Declaring participants after they're used

In Mermaid sequence diagrams, participants are auto-created when you reference them. But if you want custom aliases or ordering, declare them at the top before any messages. Declaring them after their first use can cause unexpected rendering.

Overcomplicating a single diagram

A flowchart with 40 nodes or a sequence diagram with 12 participants becomes unreadable. Split large diagrams into smaller, linked ones. Focus each diagram on one process or interaction.

What practical tips help you write diagram code faster?

Start with the happy path. Draw the main flow first, then add error handling and edge cases. This keeps the diagram focused.
Use aliases for long names. In Mermaid, write participant AS as Auth Service and use AS in messages. Shorter aliases make the code cleaner.
Test in a live editor. Use the Mermaid Live Editor or PlantUML's online server to preview as you write. Catching syntax errors early saves frustration.
Keep a personal cheat sheet. Bookmark the syntax rules you use most. You can reference our UML diagram codes cheat sheet for quick lookups.
Comment your diagram code. In Mermaid, %% this is a comment adds notes for collaborators without affecting the rendered output.
Pick one notation and stick with it. Mixing Mermaid and PlantUML in the same project creates confusion. Choose one for consistency.

How do flowchart and sequence diagram syntax compare across tools?

Feature	Mermaid	PlantUML
Flowchart declaration	`flowchart TD`	`start` / `stop` in activity diagram
Decision node	`{text}`	`if (condition) then (yes)`
Sequence message	`A->>B: message`	`A -> B : message`
Return message	`A-->>B: response`	`B --> A : response`
Notes	`note right of A: text`	`note right of A : text`
Comments	`%% comment`	`' comment`

Both tools produce similar visual output. Mermaid has broader built-in support in modern documentation platforms. PlantUML offers more diagram types and deeper customization through its skinparam system.

How do you embed these diagrams in documentation?

Most modern tools render diagram code automatically:

GitHub and GitLab Wrap Mermaid code in a mermaid code fence in any Markdown file. The platform renders it inline.
VS Code Install the Mermaid or PlantUML extension to preview diagrams while you write.
Notion Use the Mermaid code block for inline diagrams.
Static site generators Tools like MkDocs, Docusaurus, and Hugo support Mermaid through plugins.
Export to images Both Mermaid CLI and PlantUML can export to SVG or PNG for presentations and PDFs.

Quick-start checklist for writing your first diagram code

Choose your tool: Mermaid for quick integration, PlantUML for advanced features
Open a live editor (Mermaid Live or PlantUML online) and keep it side-by-side with your text editor
Write the diagram type declaration first (flowchart TD or sequenceDiagram)
List your nodes or participants
Draw connections using the correct arrow syntax
Test the render after every few lines don't write the entire diagram before checking
Add labels, notes, and conditional blocks once the basic structure works
Commit the diagram code alongside your documentation in version control

Start with a simple three-step flowchart or a two-participant sequence diagram. Once the syntax feels natural, expand to more complex diagrams. If you want to see how diagram codes fit into the bigger picture of diagramming tools, our guide on diagram codes meaning in diagramming software covers the full landscape.