mindmap-toolkit

Explore mind maps as Python trees.

mindmap-toolkit is a lightweight Python library for reading, navigating and analysing mind maps.

Instead of exposing the underlying file format, the library provides a clean and consistent tree API based on MindMap and Node objects.

The goal is to make mind maps easy to manipulate from Python, regardless of the original file format.

Currently, XMind is supported. Additional formats will be added in future releases through compatible parsers.

---

Features

• 🌳 Parse mind maps into a tree of Node objects
• 📍 Navigate directly to any node using its path
• 🏷️ Explore labels
• 🚩 Explore markers
• 🔗 Read hyperlinks
• 📝 Read notes
• 🧭 Build breadcrumbs
• 🌲 Work on complete maps or subtrees

---

Installation

pip install mindmap-toolkit

---

Quick start

Load a mind map:

from mindmap_toolkit import MindMap

mm = MindMap.load("roadmap.xmind")

Navigate to a node:

backend = mm.at("1-0")

print(backend.title)

theme01

Every node is identified by its path.

example
├── domain01          (1)
│   ├── theme01       (1-0)
│   └── theme02       (1-1)
└── domain02          (2)

---

Working on a subtree

A Node is itself the entry point to a subtree.

backend = mm.at("1")

backend.get_labels()
backend.get_markers()

This allows the same API to be used on the whole mind map or on a specific branch.

---

Labels

List every label present in the map.

labels = mm.get_labels()

Result:

{
    "important": [
        (1, 0),
        (2, 1, 3),
    ]
}

The same operation is available from any node.

backend.get_labels()

---

Markers

List every marker used in the map.

markers = mm.get_markers()

or

backend.get_markers()

---

Breadcrumbs

Retrieve the titles leading to a node.

mm.breadcrumb("2-0-1")

returns

[
    {"title": "domain02", "path": (2,)},
    {"title": "themeOne", "path": (2, 0)},
    {"title": "subject_b", "path": (2, 0, 1)},
]

---

Philosophy

mindmap-toolkit is designed around three principles.

• Simple – a small and easy-to-learn API.
• Lightweight – minimal dependencies.
• Extensible – every parser exposes the same tree API.

The parser should be transparent to the user.

mm = MindMap.load("roadmap.xmind")

Tomorrow, the same API should work with other mind map formats without changing user code.

---

Roadmap

Current version:

• ✅ XMind parser
• ✅ Tree navigation
• ✅ Labels
• ✅ Markers
• ✅ Notes
• ✅ Links
• ✅ Breadcrumbs

Future versions:

• Search nodes
• Compare mind maps
• Export
• FreeMind support
• OPML support
• Markdown outline support

---

Documentation

The complete documentation is available in the docs/ directory.

Examples are available in the examples/ directory.

---

Contributing

Contributions, bug reports and feature requests are welcome.

Please open an issue before proposing significant changes.

---

License

MIT License.