Home > Software Engineering > Mind Maps in Markdown with Mermaid.js

Mind Maps in Markdown with Mermaid.js

Simple Brainstorming in Markdown using Mermaid.js to generate mind map diagrams


Mind Maps are one of the tools I frequently find myself using as I'm organizing my thoughts. While I often use professional tools dedicated to the task, such as the exceptional XMind, I've recently discovered that I can create effective mind maps from pure markdown using Mermaid.js.

If you're not familiar with mind maps, they're effectively a visual outline stemming from a central node. Take this mind map I made for an upcoming talk I'm delivering on Polyglot Notebooks as an example:

This mind map, built using Mermaid.js, helps visualize the relationships of different topics.

While the same information could be conveyed in a hierarchical outline, mind maps de-emphasize the order of different elements and allow your mind to more easily form relationships between nodes and spot missing entries.

In this article we'll explore mind maps in Mermaid.js and see how you can be effective at building out a useful mind map without needing much more than a basic markdown editor.

Basic Mind Maps in Mermaid.js

At their core, mind maps are just outlines and so the markdown for them is very similar to an outline:

    Mermaid.js Mind Map Article
        Basic Mind Map
            Font Awesome
            Other Icons

Notice how the first element is a mindmap marker telling Mermaid.js that we're building a mind map (as opposed to some other chart type).

Next we start with a single root node. In this case that's the "Mermaid.js Mind Map Article" node.

After that, individual topics are nested inside of that main topic and its children with indentation helping identify the relationships between tasks.

Caution: if your indentation is unclear, Mermaid.js will not render anything other than a generic error message

When you put the Mermaid.js markdown in a ```mermaid block in markdown in a supported editor such as GitHub markdown or the exceptional Mermaid.js live editor, you'll get the following visual:

Admittedly, this diagram isn't quite as good as something you might get from a dedicated tool, but it's a whole lot easier to edit markdown and track it in version control than custom file formats supported by various tools out there.

Shapes in Mermaid.js Mind Maps

Sometimes you want a little more flair and variety to your mind maps - particularly in larger diagrams. To address this, Mermaid.js lets you customize the shape Mermaid.js uses to represent each topic in the mind map.

Mermaid gives us a variety of different punctuation to surround each item that roughly resembles the shape it should render.

Take a look at the following markdown as an example and its associated chart:


I have some trouble picturing when I might use a few of these shapes, but overall, the extra variety is very helpful.

Adding Icons to Mermaid.js Mind Maps

Finally, Mermaid.js allows you to add in icons from vectorized libraries like Font Awesome through specifying a few classes.

Mermaid.js does not include Font Awesome or any other icon library by default, so you'll have to make sure your page also includes the CSS files for your library of choice.

Assuming your page includes your favorite icon library, you can annotate individual nodes by using ::icon() syntax as shown below:

    ::icon(fa fa-microphone)
        ::icon(fa fa-book)
        Jupyter Notebooks
        ::icon(fa fa-rocket)
            ::icon(fa fa-code)
            ::icon(fa fa-file-code)
        Polyglot Notebooks
        ::icon(fa fa-pencil)
            ::icon(fa fa-wrench)
            ::icon(fa fa-comment)
            Variable Sharing
            ::icon(fa fa-share)
        Next Steps
        ::icon(fa fa-arrow-right)

Personally, I'd prefer to have the ::icon() lines to the right of the node they decorate, but Mermaid.js doesn't support my preferences in that regard so I'll have to make do with their conventions to get these results.

Closing Thoughts

As a dedicated user of XMind, I'm not sure if Mermaid.js mind maps are enough for me to make the switch, but I can't deny the allure of the idea of using raw markdown to generate a visually pleasing mind map.

While tools like XMind and others give you additional visual fidelity and manual control, the simplicity of Mermaid.js mixed with the ease at which you can edit it and version control your documents might win me over.

Mind Maps are a newer feature in Mermaid.js as of the time of this writing and not all tools fully support it yet. I'm personally eagerly awaiting the next release of Polyglot Notebooks that will include support for this feature because that will allow me to embed mind maps alongside markdown and code.

For now, I think I'm going to give Mermaid.js mind maps a try as my primary mind mapping tool going forward and see what happens!


  • Matt Eland
    Microsoft MVP in AI, Professional Programming Instructor

    After several decades as a software engineer and engineering manager, Matt now serves as a software engineering instructor and gets to raise up future developers and unleash them upon the world to build awesome things. Matt is a Microsoft MVP in Artificial Intelligence, runs several blogs and channels on data science and software engineering topics, is currently pursuing a master's degree in data analytics, and helps organize the Central Ohio .NET Developer Group while contributing to local and regional conferences. In his copious amounts of spare time, Matt continues to build nerdy things and looks for ways to share them with the larger community.

    View all posts


How to Make Flowcharts with Mermaid.js April 15, 2023 - 10:46 pm

[…] Mermaid.js mind maps, flowcharts can use icons to improve their readability or visual […]

Dew Drop – April 17, 2023 (#3923) – Morning Dew by Alvin Ashcraft April 17, 2023 - 7:58 am

[…] Mind Maps in Markdown with Mermaid.js and How to Make Flowcharts with Mermaid.js and Creating Timeline Charts with Mermaid.js (Matt Eland) […]

Creating SysML Requirement Diagrams in Mermaid.js April 17, 2023 - 11:22 pm

[…] markdown into full diagrams. While it supports many common diagram types such as sequence diagrams, mind maps, entity relationship diagrams, and sequence diagrams, it also supports a few I've rarely seen […]


Leave a Reply

Related Content

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Accept Read More