L05 Mermaid Flowcharts

title: "Mermaid Flowcharts — Creating Process Diagrams" weight: 5 description: "Learn to create Mermaid flowcharts for technical documentation: node types, edge styles, subgraphs, styling, and advanced features for process and workflow diagrams." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagrams] }

Mermaid flowcharts are the most commonly used diagram type in technical documentation, showing processes, workflows, and decision trees with clear visual syntax.

In this lesson, you will learn advanced Mermaid flowchart techniques including node shapes, edge types, subgraphs, styling with classDef, and interactive features for documentation.

What You'll Learn

You will master Mermaid flowchart syntax: different node shapes, edge styles, subgraph grouping, custom styling, click events, and best practices for creating clear process diagrams.

Why It Matters

Flowcharts are the universal language of processes. A well-designed flowchart communicates a deployment workflow, installation process, or algorithm in seconds. Mastering flowcharts covers 50 percent of diagram needs.

Real-World Use

DodaTech uses flowcharts for every installation guide. The DodaZIP setup flowchart reduced installation support tickets by 60 percent by visually showing prerequisites and decision points.

flowchart TD
  A[Start Installation] --> B{OS Type?}
  B -->|Windows| C[Download .exe]
  B -->|macOS| D[Download .dmg]
  B -->|Linux| E[Use Package Manager]
  C --> F[Run Installer]
  D --> F
  E --> F
  F --> G{Installation Success?}
  G -->|Yes| H[DodaZIP Ready]
  G -->|No| I[Check Logs]
  I --> J[Fix Issues]
  J --> F
  H:::success
  I:::warning
  classDef success fill:#4caf50,color:#fff
  classDef warning fill:#f90,color:#fff

def create_decision_flowchart(question, yes_branch, no_branch):
    """Generate a Mermaid flowchart with a decision node."""
    diagram = "flowchart TD\n"
    diagram += f"  Q{{'{question}'}}\n"
    diagram += f"  Q -->|Yes| Y[{yes_branch['label']}]\n"
    diagram += f"  Q -->|No| N[{no_branch['label']}]\n"
    if yes_branch.get("next"):
        diagram += f"  Y --> {yes_branch['next']}\n"
    if no_branch.get("next"):
        diagram += f"  N --> {no_branch['next']}\n"
    return diagram

flow = create_decision_flowchart(
    "Continue deployment?",
    {"label": "Run pipeline", "next": "D[Deploy]"},
    {"label": "Rollback", "next": "R[Review logs]"}
)
print(flow)

def apply_subgraph(nodes, edges, group_label):
    """Group nodes into a Mermaid subgraph."""
    output = f"subgraph {group_label}\n"
    for node_id, label in nodes:
        output += f"  {node_id}[{label}]\n"
    for src, tgt in edges:
        output += f"  {src} --> {tgt}\n"
    output += "end\n"
    return output

frontend = [("F1", "React App"), ("F2", "API Client")]
frontend_edges = [("F1", "F2")]
print(apply_subgraph(frontend, frontend_edges, "Frontend"))

def add_interactive_click(diagram_text, node_id, url):
    """Add a click event to a Mermaid node."""
    return diagram_text + f"\nclick {node_id} \"{url}\""

diagram = "flowchart LR\n  A[Docs] --> B[Code]\n"
diagram = add_interactive_click(diagram, "A", "/docs/")
print(diagram)

Teacher Mindset

Think of flowcharts as stories. Every flowchart has a beginning (start node), a middle (process and decision nodes), and an end (terminal node). A good flowchart tells a complete story without forcing the reader to search for missing steps. If you have ever assembled furniture with an incomplete diagram, you know how frustrating missing steps are. Do not do that to your readers.

Common Mistakes in Mermaid Flowcharts

1. No Terminal Nodes

Flowcharts without start and end nodes leave readers unsure where the process begins and ends. Always mark entry and exit points clearly.

2. Crossing Lines Without Bridges

Lines that cross without bridges create confusion. Reorganize node positions to minimize crossings. Use subgraphs to group related nodes.

3. Inconsistent Node Shapes

Using different shapes randomly confuses readers. Use rectangles for processes, diamonds for decisions, and rounded rectangles for start-end. Follow a consistent convention.

4. Labels That Are Too Long

Node labels longer than 3 to 5 words create wide diagrams that do not fit on screen. Use abbreviations or split into multiple nodes.

5. Not Using Edge Labels

Arrows without labels force readers to guess the transition condition. Label every arrow that represents a decision or specific condition.

Practice Questions

1. What node shape represents a decision in Mermaid flowcharts? A diamond shape created with { } syntax. Example: Q{Is valid?} creates a diamond-shaped decision node.

2. How do you create a subgraph in Mermaid? Use the subgraph keyword: subgraph Group Name ... end. All nodes between subgraph and end are visually grouped.

3. What is the difference between --> and === in Mermaid edges? --> creates a solid arrow. === creates a thick arrow. Use -.-> for dotted arrows and ==> for bold arrows.

4. How do you apply styles to specific nodes? Define a class with classDef className fill:#color,stroke:#color and apply with nodeId:::className. Multiple nodes can share a class.

5. Challenge: Create a flowchart for a deployment pipeline including build, test, stage, and production stages. Include decision points for test success and manual approval gates. Use subgraphs for each stage.

FAQ

{{< faq "How do I add notes or comments to a flowchart?" "Use click events for tooltips: click nodeId "tooltip text". Mermaid does not have native comment nodes, but you can create notes as separate nodes connected with dotted lines." >}}

Mini Project

Document a real workflow from your project or daily work as a Mermaid flowchart. Include at least 10 nodes, 2 decision points, 1 subgraph, and styled success-failure nodes. Test the diagram renders correctly and embed it in a documentation page.

What's Next

Mermaid Sequence in the next lesson.