Metadata-Version: 2.4
Name: mindmap-toolkit
Version: 0.1.1
Summary: Explore mind maps as Python trees
Author: FEVRE Lionel
License: MIT
Project-URL: Homepage, https://github.com/linol/mindmap-toolkit.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xmindparser
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install mindmap-toolkit
```

---

## Quick start

Load a mind map:

```python
from mindmap_toolkit import MindMap

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

Navigate to a node:

```python
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.

```python
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.

```python
labels = mm.get_labels()
```

Result:

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

The same operation is available from any node.

```python
backend.get_labels()
```

---

## Markers

List every marker used in the map.

```python
markers = mm.get_markers()
```

or

```python
backend.get_markers()
```

---

## Breadcrumbs

Retrieve the titles leading to a node.

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

returns

```python
[
    {"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.

```python
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.


