Mermaid Flowchart Scripting Examples with Annotations: Complete Guide

Mermaid flowchart scripting examples with annotations are one of the fastest ways to document processes, explain system logic, and collaborate with your team all using plain text. If you've ever needed to add notes, labels, or interactive click events to your Mermaid diagrams and weren't sure how, you're in the right place. Annotations turn a basic flowchart into something that actually communicates meaning, and getting them right saves you hours of back-and-forth explanations.

What Does "Annotations" Mean in Mermaid Flowcharts?

In Mermaid, annotations refer to the extra text, labels, and metadata you attach to nodes and connections in a flowchart. This includes:

Node text the descriptive label inside each shape
Link labels text placed on arrows to explain the relationship between steps
HTML comments developer-facing notes that don't render in the diagram but help your team understand the code
Click events interactive annotations that link nodes to URLs or trigger JavaScript functions
Directives and configuration settings that change how the diagram looks and behaves

Think of annotations as the "why" behind each box and arrow. Without them, a flowchart shows structure. With them, it tells a story.

How Do You Add Basic Node and Link Annotations?

The simplest form of annotation in a Mermaid flowchart is the text you place inside nodes and on the edges connecting them. Here's a straightforward example:

flowchart TD A[Customer places order] --> B{Is item in stock?} B -->|Yes| C[Process payment] B -->|No| D[Notify customer of backorder] C --> E[Ship item] D --> F[Offer alternative product]

In this example, every node has a descriptive label, and the |Yes| and |No| on the arrows are link annotations. They tell the reader exactly what condition leads down each path. This is the foundation that most beginners learning Mermaid diagram syntax need to understand first.

What node shapes work best for different annotations?

Mermaid gives you several shape options, and using the right one makes your annotation more meaningful:

[text] Rectangle for standard process steps
{text} Diamond for decisions or conditions
(text) Rounded rectangle for start/end points
[[text]] Subroutine shape for reusable processes
[(text)] Cylinder shape for databases or storage
[/text/] Parallelogram for input/output operations

Matching shape to meaning is a subtle but effective annotation technique. A diamond signals a decision point, so readers immediately expect a yes/no or if/else branch without you needing to explain it in words.

How Do You Add HTML Comments as Non-Visible Annotations?

Sometimes you need to leave notes for other developers working on the same diagram file. Mermaid supports HTML-style comments that won't appear in the rendered output:

flowchart TD %% This section handles the user registration flow %% Last updated: 2024-01 by the backend team A[User submits form] --> B[Validate email] B -->|Valid| C[Create account] %% TODO: Add email verification step here B -->|Invalid| D[Show error message]

The double-percent syntax (%%) creates a comment. It's a clean way to annotate your Mermaid source code with context, ownership info, or open questions. These comments stay visible to anyone reading the raw script but disappear in the diagram output. If you're working on multiple diagram types, our sequence diagram cheat sheet covers similar comment conventions across diagram types.

How Do You Add Click Event Annotations to Flowchart Nodes?

One of Mermaid's more powerful annotation features is the ability to make nodes interactive. You can bind a click event to any node, linking it to a URL or a JavaScript callback:

flowchart TD A[View Documentation] --> B[Read API Spec] B --> C[Run Test Suite] click A "https://example.com/docs" "Open documentation" click B "https://example.com/api" "View API specification" click C callback "Run the test suite"

The click keyword takes the node ID, a URL or function name, and an optional tooltip text. The tooltip is itself an annotation it gives the user a hint about what will happen when they click. This works well for living documentation where your flowchart doubles as a navigation tool.

What's the full click annotation syntax?

There are two forms:

click nodeId "URL" "tooltip text" links to a web address
click nodeId functionName "tooltip text" calls a JavaScript function (requires the Mermaid security level to be set to loose)

For example:

click A "https://example.com" "Go to homepage"

This makes your flowchart annotation interactive and useful in dashboards or wikis where users can click through to related resources.

How Do You Annotate Flowcharts with Style Directives?

Beyond text, visual styling acts as a form of annotation. Mermaid lets you apply CSS-style formatting to individual nodes or classes of nodes:

flowchart TD A[Normal step] --> B[Critical step] B --> C[Normal step] style B fill:#ff9999,stroke:#cc0000,stroke-width:2px

This colors the "Critical step" node red, visually flagging it as something that needs attention. You can also define reusable styles with classDef:

classDef warning fill:#fff3cd,stroke:#ffc107,color:#856404 classDef success fill:#d4edda,stroke:#28a745,color:#155724

Then apply them: class B warning

Color-coding nodes is an annotation layer that helps non-technical readers scan a diagram and immediately spot risks, approvals, or completed steps.

Can You Add Annotations to the Diagram Title?

Yes Mermaid supports a title directive that serves as a top-level annotation for the entire chart:

--- title: Order Processing Flow Q1 2024 Revision ---

flowchart TD A[Receive order] --> B[Process]

The title renders above the diagram and tells viewers what they're looking at, when it was last updated, and what scope it covers. It's a small thing, but on a wiki page with dozens of diagrams, it prevents confusion.

What Are Common Mistakes with Mermaid Flowchart Annotations?

Here are the errors we see most often:

Putting special characters directly in node text. Characters like [, {, (, and # break the parser. Wrap problematic text in quotes: A["Label with (parentheses)"]
Forgetting to quote annotation text with spaces. If your link label has spaces and you don't use pipes (|label|) or quotes, Mermaid will throw a syntax error
Over-annotating. Cramming every node with long explanations makes the diagram unreadable. Use short node labels and put the detail in comments or linked documentation
Not testing interactive annotations. Click events silently fail if the security level is set to strict (the default). You need to change it to loose or antisanitize for JavaScript callbacks to work
Inconsistent shape meanings. If a diamond means "decision" in one part of your flowchart and "process" in another, your shape annotations contradict each other

How Do You Build a Fully Annotated Flowchart Step by Step?

Let's walk through a realistic example: a customer support ticket process with all the annotation layers we've covered.

--- title: Support Ticket Resolution Flow ---


flowchart TD

  %% Ticket lifecycle from submission to resolution

  %% Owner: Support Engineering Team

  %% Last reviewed: March 2024
  A([Customer submits ticket]) --> B[Triage: Read and categorize]

  B --> C{Is it a known issue?}

  C -->|Yes| D[Apply known fix from KB]

  C -->|No| E[Assign to specialist]

  E --> F[Investigate root cause]

  F --> G[Implement fix]

  G --> H[QA validation]

  H -->|Pass| I([Close ticket and notify customer])

  H -->|Fail| G
  classDef startEnd fill:#d4edda,stroke:#28a745

  classDef decision fill:#fff3cd,stroke:#ffc107

  classDef process fill:#cce5ff,stroke:#004085
  class A,I startEnd

  class C decision

  class B,D,E,F,G,H process

click A "https://support.example.com/submit" "Customer portal" click D "https://kb.example.com" "Knowledge base"

This single diagram uses six annotation types: title, comments, descriptive node labels, link labels, class-based styling, and click events. It tells the whole story at a glance while remaining interactive and well-documented for developers.

For more advanced diagram structures, the class diagram markup guide covers how to use similar annotation patterns in UML-style diagrams.

Quick Checklist: Annotating Your Next Mermaid Flowchart

Write short, clear node labels that explain the action or state
Use link labels (|text|) on decision branches to show conditions
Add %% comments for developer context, ownership, and TODOs
Include a title directive so readers know the diagram's scope
Apply classDef styles to visually group or flag important nodes
Use click annotations to link nodes to docs, tickets, or dashboards
Quote any text containing special characters or spaces
Test interactive annotations with the correct security level setting
Keep annotations concise link out for details instead of overloading the chart
Review your shape conventions so they're consistent throughout

Next step: Take one existing flowchart you've already written and add at least three annotation layers a title, color-coded node classes, and descriptive link labels on every decision branch. You'll notice the difference immediately in how quickly other people understand it.