Mermaid Mindmap: Complete Syntax Guide with Examples

Mermaid mindmaps let you embed branching knowledge maps directly in Markdown files using plain text. Write the structure once as indented text, commit it alongside your code or documentation, and any Mermaid-compatible renderer displays a visual radial diagram. No design tool, no exported image, no file to keep in sync with reality.

TL;DR: Start with mindmap, add an indented root node (use ((text)) for a circle), then branch out using indentation. Each level of indent creates a child. Supported shapes: ((circle)), [square], (rounded), {{hexagon}}, ))cloud((, >bang]. Add Font Awesome icons with ::icon(fa fa-name). GitHub does not render mindmaps — use MacMD Viewer locally or mermaid.live online.

What Are Mermaid Mindmaps Good For?

Mermaid mindmaps are the right tool when you need a hierarchical knowledge structure that lives in version control. They work well for brainstorming sessions documented in a README, project scope overviews in architecture decision records, feature breakdowns in product wikis, and onboarding guides that map a system's components visually.

The key advantage over a dedicated mindmap tool like XMind or MindNode is portability. A Mermaid mindmap is plain text — it diffs cleanly in pull requests, renders in any compatible viewer without a proprietary format, and lives in the same repository as the code or documentation it describes. When the architecture changes, updating the mindmap is a text edit, not a save-and-export cycle.

They are not a replacement for XMind or MindNode when you need drag-and-drop rearrangement, image attachments, relationship links between branches, or presentation export. The Mermaid mindmap is deliberately constrained: strict hierarchy, no cross-links, text only (plus icons). Within those limits, it covers most documentation use cases perfectly.

How Do You Write Basic Mermaid Mindmap Syntax?

Every Mermaid mindmap starts with the keyword mindmap on its own line inside a fenced code block. The entire structure is expressed through indentation — there is no explicit edge or arrow syntax. Here is a minimal working example:

mindmap
  root((MacMD Viewer))
    Features
      Syntax highlighting
      Mermaid diagrams
      Dark mode
    Pricing
      One-time $19.99
      No subscription
    Platform
      macOS only
      Native app

Breaking down the structure:

• mindmap — the diagram type declaration, always the first line
• root((MacMD Viewer)) — the root node, wrapped in (( )) to render as a circle
• Features, Pricing, Platform — first-level branches, indented 4 spaces under root
• Syntax highlighting, Mermaid diagrams, etc. — second-level sub-branches, indented 6 spaces

The rule is simple: every item's depth in the tree is determined entirely by its indentation relative to the item above it. Adding two more spaces makes something a child; removing two spaces makes it a sibling.

There is no explicit root keyword — the first indented item after mindmap is automatically treated as the root node.

What Node Shapes Are Available?

Mermaid mindmaps support six distinct shapes applied by wrapping a node's text in different delimiters. These can be used on the root or on any branch at any depth.

mindmap
  root((Project Overview))
    (Rounded rectangle)
    [Square rectangle]
    ((Circle node))
    {{Hexagon node}}
    ))Cloud shape((
    >Bang shape]

Shape reference:

The root node most commonly uses ((double parentheses)) because the circle shape stands out visually from the rectangular branches. For the rest of the tree, mixing shapes sparingly — one shape per semantic category — makes the diagram easier to scan.

How Do You Add Icons to Mindmap Nodes?

Mermaid mindmaps support Font Awesome icons via the ::icon() syntax. Add it on the same line as the node text, after the label:

mindmap
  root((Tech Stack))
    Backend
      ::icon(fa fa-server)
      Node.js
      PostgreSQL
    Frontend
      ::icon(fa fa-desktop)
      React
      Tailwind CSS
    DevOps
      ::icon(fa fa-cloud)
      Docker
      GitHub Actions

The ::icon(fa fa-name) directive renders a Font Awesome icon above the node text. The icon name follows the Font Awesome 5/6 class naming convention (fa-server, fa-cloud, fa-code, etc.).

Icons are purely visual — they do not affect the tree structure or indentation. They work best on first-level branches to visually categorize major topic areas, making the diagram readable at a glance without requiring readers to study every label.

If your renderer does not include Font Awesome (some self-hosted Mermaid setups omit it), the ::icon() directive is silently ignored and the node renders with text only.

How Do You Build a Real Mindmap — Software Architecture Example?

Here is a production-quality mindmap for a software project architecture. This is the kind of diagram that belongs in a README or architecture overview document alongside written descriptions:

mindmap
  root((E-Commerce Platform))
    Frontend
      ::icon(fa fa-desktop)
      Next.js App Router
        Pages
          Product listing
          Cart
          Checkout
        State
          Zustand store
          React Query
    Backend
      ::icon(fa fa-server)
      API Layer
        REST endpoints
        GraphQL gateway
      Services
        Auth service
        Payment service
        Email service
    Data
      ::icon(fa fa-database)
      PostgreSQL
        Users table
        Orders table
        Products table
      Redis
        Session cache
        Rate limiting
    Infrastructure
      ::icon(fa fa-cloud)
      Docker
      GitHub Actions CI
      VPS deployment

This example demonstrates all the key patterns working together: a circle root, first-level branches with icons, and two levels of sub-branches for detail. The diagram is readable in 30 seconds — which is the benchmark for a good architecture overview.

For comparison, a project planning mindmap is often flatter, organized around phases rather than components:

mindmap
  root((Product Launch))
    Research
      User interviews
      Competitor analysis
      Market sizing
    Design
      Wireframes
      Prototype
      Usability testing
    Development
      Backend API
      iOS app
      Web dashboard
    Launch
      Beta program
      Press outreach
      App Store submission
    Post-Launch
      Support
      Analytics review
      Roadmap v2

Both examples can be pasted directly into any .md file and will render wherever Mermaid mindmaps are supported.

How Do Node Classes Work?

Mermaid mindmaps support custom CSS class assignment via the :::className suffix:

mindmap
  root((System))
    Critical path:::urgent
      Auth service
      Payment gateway
    Nice to have:::optional
      Dark mode
      Export to PDF

The :::className suffix attaches a CSS class to the rendered node, allowing theme-level styling. In practice, class-based styling only works when you control the Mermaid theme or embedding page CSS — in most documentation renderers, classes are present in the DOM but unstyled. The crit visual effect from Gantt charts has no equivalent here; class-based node coloring requires custom CSS in your rendering environment.

Where Does Mermaid Render Mindmaps?

Platform support for mindmaps is more limited than for flowcharts or sequence diagrams, because mindmap was a later addition (v9.4):

• GitHub — does not render mindmaps as of 2025. The code block displays as plain text in READMEs, pull requests, and wikis. This is a meaningful gap if your documentation lives primarily on GitHub.
• GitLab — renders Mermaid mindmaps natively in Markdown files, wikis, and issue descriptions.
• Mermaid Live Editor — full support. Paste your mindmap syntax at mermaid.live and see it rendered instantly. Ideal for iterating on the structure before committing.
• MacMD Viewer — native macOS app (download here) that renders all Mermaid diagram types — including mindmaps — in local .md files. Open a file and the mindmap appears instantly with live file watching. The bundled QuickLook extension renders mindmaps when you press Space on a .md file in Finder, without opening the full app. No internet connection required. $19.99 one-time.
• Notion — create a code block, set the language to mermaid. Support depends on Notion's bundled Mermaid version; mindmap rendering may vary.
• VS Code — requires the Markdown Preview Mermaid Support extension. After installation, Cmd+Shift+V opens a preview that renders mindmaps inline.

For a full comparison of online rendering options, see the online Mermaid diagram tools guide. For the live browser playground specifically, see the Mermaid Live Editor guide.

What Are the Limitations Compared to Dedicated Mindmap Tools?

Mermaid mindmaps cover the essentials for documentation use cases, but they differ meaningfully from XMind, MindNode, or Obsidian Canvas. Understanding the limits helps you choose the right tool:

No cross-links between branches. This is the most significant constraint. In XMind, you can draw a relationship arrow from any node to any other node, regardless of where they sit in the tree. Mermaid mindmaps are strictly hierarchical — a node can only connect to its parent. If you need a graph with arbitrary connections, use a Mermaid flowchart instead.

No drag-and-drop rearrangement. The hierarchy is locked to indentation. Reorganizing the tree means editing the text directly. For exploratory brainstorming sessions where you are rapidly moving ideas around, a visual mindmap tool is more ergonomic.

No image attachments. Nodes are text-only (plus Font Awesome icons). You cannot embed an image, screenshot, or file attachment inside a Mermaid mindmap node.

Read-only rendering. The rendered diagram is purely visual — you cannot click nodes, collapse branches interactively, or edit the diagram in place. Interaction happens only in the source text.

Limited styling per node. Beyond node shapes and CSS classes (which require renderer support), there is no way to set colors, font sizes, or custom borders on individual nodes without controlling the full Mermaid theme.

The advantage over dedicated tools is precisely what makes the format constrained: because a Mermaid mindmap is plain text, it lives in a git repository, shows clean diffs in code review, and renders anywhere Mermaid is supported — all without requiring a proprietary file format or a separate application to open it.

How Do You Preview Mermaid Mindmaps Locally on Mac?

Since GitHub does not render mindmaps, local preview is particularly important during authoring. Three practical options:

1. MacMD Viewer ($19.99) — open any .md file containing a Mermaid mindmap and see it rendered in real time. File watching means edits in your text editor update the preview instantly. The QuickLook extension renders mindmaps in Finder when you press Space, making it easy to spot-check files without opening the full app. Available as a one-time purchase on the Mac App Store.
2. Mermaid Live Editor — free browser tool. Paste your mindmap syntax on the left, see the rendered output on the right. Export as SVG or PNG. Best for quick validation of syntax before committing.
3. VS Code with Markdown Preview Mermaid Support — installs in seconds from the extension marketplace. Cmd+Shift+V toggles a side-by-side preview that supports mindmaps.

For teams using Mermaid flowcharts, class diagrams, or ER diagrams alongside mindmaps, MacMD Viewer handles all diagram types in a single application rather than requiring separate preview tools.

Conclusion

Mermaid mindmap syntax is intentionally minimal: declare mindmap, indent your root node, and branch outward through indentation depth. Six node shapes let you add visual hierarchy, Font Awesome icons add scannable category markers, and the entire diagram lives as plain text alongside your code or documentation.

The main practical constraint is GitHub's lack of mindmap support — for projects hosted there, use MacMD Viewer locally or mermaid.live to preview before committing, then verify the rendered output on a GitLab mirror or in your documentation platform.

For other Mermaid diagram types, see the flowchart syntax guide, the class diagram guide, and the ER diagram guide. To explore Mermaid diagrams interactively in the browser without installing anything, the Mermaid viewer tool renders any diagram type on demand.