Mind Maps in Markdown with Mermaid.js

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:

mindmap
    Mermaid.js Mind Map Article
        Basic Mind Map
            Indentation
        Shapes
            Default
            Square
            Rounded
            Circle
            Bang
            Cloud
            Hexagon            
        Icons
            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 code 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:

mindmap
    Shapes
        Default
        [Square]
        (Rounded)
        ((Circle))
        ))Bang((
        )Cloud(

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:

mindmap
    Talk
    ::icon(fa fa-microphone)
        Notebooks
        ::icon(fa fa-book)
        Jupyter Notebooks
        ::icon(fa fa-rocket)
            IDEs
            ::icon(fa fa-code)
            Anaconda
            ::icon(fa fa-file-code)
        Polyglot Notebooks
        ::icon(fa fa-pencil)
            Installation
            ::icon(fa fa-wrench)
            Languages
            ::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!