L04 Mermaid Basics

title: "Mermaid Basics — Getting Started with Diagram Syntax" weight: 4 description: "Learn Mermaid basics: installing, writing your first diagram, syntax fundamentals, rendering options, and integrating Mermaid diagrams into Markdown documentation for version-controlled visuals." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagrams] }

Mermaid is a JavaScript-based diagramming tool that renders diagrams from Markdown-style text syntax, enabling version-controlled, reviewable diagrams embedded directly in documentation.

In this lesson, you will learn Mermaid fundamentals: syntax basics, diagram types supported, rendering options, and how to embed Mermaid diagrams in your documentation pages.

What You'll Learn

You will learn to write basic Mermaid syntax, create your first diagram, understand rendering options, and embed diagrams in Markdown documentation using the DodaTech Python generator or Hugo.

Why It Matters

Mermaid is the most popular diagram-as-code tool because it integrates natively with GitHub, GitLab, and most static site generators. You write diagrams in text, commit them to version control, and they render automatically.

Real-World Use

All DodaTech documentation uses Mermaid for flowcharts, sequence diagrams, and architecture diagrams. The text-based format enables code review of diagram changes in pull requests.

flowchart LR
  A[Write Mermaid Syntax] --> B[Commit to Git]
  B --> C[Review in PR]
  C --> D[Build Renders Diagram]
  D --> E[Embedded in Docs]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

def create_mermaid_flowchart(nodes, edges):
    """Generate Mermaid flowchart syntax programmatically."""
    lines = ["flowchart TD"]
    for node_id, label in nodes:
        lines.append(f"  {node_id}[{label}]")
    for source, target in edges:
        lines.append(f"  {source} --> {target}")
    return "\n".join(lines)

nodes = [("A", "Start"), ("B", "Process"), ("C", "End")]
edges = [("A", "B"), ("B", "C")]
diagram = create_mermaid_flowchart(nodes, edges)
print(diagram)

def validate_mermaid_syntax(diagram_text):
    """Basic validation of Mermaid syntax."""
    errors = []
    if not any(kw in diagram_text for kw in ["flowchart", "sequenceDiagram",
                                              "classDiagram", "gantt"]):
        errors.append("Missing diagram type declaration")
    if "graph" in diagram_text and "flowchart" not in diagram_text:
        errors.append("Consider using 'flowchart' instead of 'graph'")
    lines = diagram_text.strip().split("\n")
    if len(lines) < 3:
        errors.append("Diagram too short - minimum 3 lines")
    return errors or ["Syntax looks valid"]

print(validate_mermaid_syntax("flowchart LR\n  A[Hello] --> B[World]"))

def embed_mermaid_in_markdown(diagram_text, caption=None):
    """Wrap Mermaid syntax in Markdown code block."""
    md = f"```mermaid\n{diagram_text}\n```\n"
    if caption:
        md += f"\n*{caption}*\n"
    return md

diagram = embed_mermaid_in_markdown(
    "flowchart LR\n  A[Input] --> B[Output]",
    "Simple data flow diagram"
)
print(diagram)

Teacher Mindset

Learning Mermaid syntax is like learning a new keyboard shortcut. At first, it feels slower than using a mouse. But once you memorize the patterns, you create diagrams faster than you ever could with drag-and-drop. Start with the three most common types: flowchart, sequence, and class. Master those before exploring advanced types.

Common Mistakes in Mermaid Basics

1. Using Deprecated Graph Keyword

Mermaid 10+ recommends "flowchart" instead of "graph". Use "flowchart LR" for left-to-right or "flowchart TD" for top-to-bottom.

2. Missing Spaces Around Node Labels

Mermaid requires spaces inside brackets. [Hello] works. [Hello] without surrounding spaces may fail. Always use [Label Text] with spaces.

3. Forgetting to Close Brackets

Unclosed brackets cause rendering errors. Every [ needs a matching ]. Every ( needs a matching ). Check bracket pairs before committing.

4. No Line Breaks Between Statements

Mermaid statements should be on separate lines. Putting multiple arrows on one line causes parsing errors. One statement per line.

5. Using Incompatible Special Characters

Characters like parentheses, quotes, and slashes inside node labels may break rendering. Wrap labels in quotes: A["Node (with parens)"].

Practice Questions

1. What is the basic syntax for a Mermaid flowchart? Start with "flowchart LR" for left-to-right or "flowchart TD" for top-to-bottom. Define nodes with id[label] and edges with id1 --> id2.

2. How do you render Mermaid diagrams in documentation? Mermaid renders natively in GitHub and GitLab Markdown. For static sites, include the Mermaid JavaScript library or use a build-time renderer. The DodaTech Python generator renders Mermaid during build.

3. What are the most useful Mermaid diagram types for technical writing? Flowchart (processes), sequence diagram (interactions), class diagram (data models), and Gantt chart (timelines). These cover 90 percent of documentation needs.

4. How do you add styling to Mermaid nodes? Use class definitions to apply styles. Define a class with classDef className fill:#color,stroke:#color and apply with nodeId:::className.

5. Challenge: Write a Mermaid flowchart for a process you perform daily, such as your morning routine or deployment pipeline. Include at least 5 nodes and 2 decision points.

FAQ

Mini Project

Create three Mermaid diagrams: a flowchart showing a software deployment process, a sequence diagram showing an API request flow, and a class diagram showing a simple data model. Embed all three in a Markdown page with introductory text for each.

What's Next

Mermaid Flowcharts in the next lesson.