L03 Mermaid Deep

title: "Mermaid Deep Dive — Advanced Features and Techniques" weight: 3 description: "Deep dive into Mermaid advanced features: themes and configuration, custom styling, interactive elements, advanced diagram types, and optimization for documentation rendering." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagram-as-code] }

Mermaid advanced features include themes, custom styling with classDef, interactive click events, mindmaps, timeline diagrams, and configuration options for optimized documentation rendering.

In this lesson, you will learn advanced Mermaid techniques beyond basic flowcharts and sequence diagrams, including configuration, theming, interactivity, and less common diagram types.

What You'll Learn

You will learn Mermaid configuration and theming, custom styling with classDef and style keywords, interactive click events, advanced diagram types like mindmap and timeline, and rendering optimization.

Why It Matters

Basic Mermaid covers 80 percent of needs. Advanced features cover the remaining 20 percent that makes diagrams look professional, interactive, and tailored to your documentation brand.

Real-World Use

DodaTech uses Mermaid themes that match the Doda Browser brand colors. Interactive click events on architecture diagrams link to detailed component documentation.

mindmap
  root((Mermaid))
    Flowcharts
      Node Shapes
      Edge Styles
      Subgraphs
    Sequence
      Participants
      Messages
      Activations
    Class
      Relationships
      Namespaces
    Advanced
      Themes
      Click Events
      Custom Styles

def configure_mermaid_theme(primary_color, secondary_color):
    """Generate Mermaid initialization config with custom theme."""
    config = {
        "theme": "base",
        "themeVariables": {
            "primaryColor": primary_color,
            "secondaryColor": secondary_color,
            "tertiaryColor": "#ffffff",
            "primaryBorderColor": primary_color,
            "lineColor": "#333333",
            "fontSize": "14px",
            "fontFamily": "Inter, sans-serif"
        }
    }
    return config

config = configure_mermaid_theme("#2563eb", "#f97316")
print(config)

def add_click_events(diagram_text, click_map):
    """Add interactive click events to Mermaid nodes."""
    result = diagram_text
    for node_id, url in click_map.items():
        result += f"\nclick {node_id} \"{url}\""
    return result

diagram = "flowchart LR\n  A[Docs] --> B[API]"
click_map = {"A": "/docs/", "B": "/api/"}
print(add_click_events(diagram, click_map))

def create_mindmap_diagram(root, children):
    """Generate a Mermaid mindmap diagram."""
    lines = ["mindmap", f"  ({root})"]
    for child in children:
        if isinstance(child, dict):
            for key, subchildren in child.items():
                lines.append(f"    {key}")
                for sub in subchildren:
                    lines.append(f"      {sub}")
        else:
            lines.append(f"    {child}")
    return "\n".join(lines)

diagram = create_mindmap_diagram("Technical Writing",
    ["Tutorials", "API Docs", {"Advanced": ["Diagrams", "SEO", "Localization"]}])
print(diagram)

Teacher Mindset

Think of Mermaid configuration as the dashboard of a car. The default settings work fine, but adjusting the mirrors, seat position, and climate control makes the ride comfortable. Similarly, default Mermaid output is functional, but custom themes make diagrams feel like they belong to your brand.

Common Mistakes in Advanced Mermaid

1. Overusing Custom Styles

Applying unique styles to every node creates visual chaos. Use 2 to 3 class definitions maximum. Apply them consistently for similar node types.

2. Misconfiguring Theme Variables

Wrong theme variable names cause silent failures. Check the Mermaid documentation for correct variable names. Test configuration changes immediately.

3. Click Events That Do Not Work in All Environments

Click events require JavaScript. They work in HTML renderings but not in PDF or image exports. Ensure critical information is not hidden behind click interactions.

4. Mindmaps With Too Many Branches

Mindmaps with 30+ nodes become unreadable. Limit to 15 to 20 nodes. Use sub-branches for deeper hierarchies.

5. Ignoring Rendering Engine Differences

Mermaid renders differently in GitHub, VS Code, and custom sites. Test your diagrams in the target rendering environment.

Practice Questions

1. How do you customize Mermaid colors? Use themeVariables in the Mermaid initialization config. Set primaryColor, secondaryColor, lineColor, and other variables to your brand colors.

2. What are click events in Mermaid? Click events make nodes interactive. When a user clicks a node, it navigates to a URL. Use click nodeId "url" syntax after the diagram body.

3. What is a mindmap diagram and when should you use it? A mindmap shows hierarchical relationships with a central root and branching subtopics. Use it for brainstorming, content organization, and concept overviews.

4. How do you create a timeline diagram in Mermaid? Use the timeline keyword followed by sections and events: timeline\n section Title\n Event1: Description\n Event2: Description.

5. Challenge: Create a Mermaid configuration that matches your project's brand colors. Apply it to three different diagram types. Verify the output renders correctly in your documentation platform.

FAQ

{{< faq "How do I add tooltips to Mermaid nodes?" "Use the click event with a tooltip string as the second parameter: click nodeId "Tooltip text". Tooltips display on hover." >}}

Mini Project

Create a themed documentation page with 3 Mermaid diagrams using a custom configuration. Include a flowchart with styled nodes, a mindmap for content overview, and a timeline for version history. Apply consistent brand colors across all diagrams.

What's Next

Mermaid C4 Diagrams in the next lesson.