cruldra/xmind-processor

XMind Processor

Programmatically work with XMind mind map files (.xmind format).

Capabilities

This skill provides Python utilities to:

1. Parse existing .xmind files and extract content.json
2. Create new .xmind files from templates
3. Insert topics programmatically using JSONPath expressions
4. Modify background colors and other properties
5. Batch process multiple mind maps

Core Scripts

All scripts are located in scripts/ directory.

xmind_utils.py - Core Utilities

from scripts.xmind_utils import read_content, write_content, modify_content

# Read xmind file
content = read_content("file.xmind")

# Write modified content back
write_content("file.xmind", new_content, output_path="output.xmind")

# Modify with a function
modify_content("file.xmind", lambda c: do_something(c), output_path="output.xmind")

create_xmind.py - Create New Files

from scripts.create_xmind import create_xmind

# Create blank mind map
create_xmind("new.xmind")

# Create with custom titles
create_xmind(
    "new.xmind",
    sheet_title="My Canvas",
    root_topic_title="Central Topic"
)

Command line:

uv run scripts/create_xmind.py output.xmind --sheet-title "Project" --root-topic "Goals"

insert_topic.py - Add Topics

from scripts.insert_topic import insert_topic, insert_topics_batch

# Insert single topic
insert_topic(
    "file.xmind",
    parent_jsonpath="$[0].rootTopic",
    topic_title="New Child Topic",
    output_path="output.xmind"
)

# Batch insert
insert_topics_batch(
    "file.xmind",
    "$[0].rootTopic.children.attached[0]",
    ["Sub-topic 1", "Sub-topic 2", "Sub-topic 3"],
    output_path="output.xmind"
)

Command line:

# List available paths
uv run scripts/insert_topic.py file.xmind --list-topics

# Insert topic
uv run scripts/insert_topic.py file.xmind --parent '$[0].rootTopic' --title "New Topic"

# Batch insert
uv run scripts/insert_topic.py file.xmind --parent '$[0].rootTopic.children.attached[0]' --titles "A" "B" "C"

set_background.py - Styling

from scripts.set_background import set_sheet_background, set_all_sheets_background, list_sheets

# Set single sheet background
set_sheet_background("file.xmind", color="#000000FF", sheet_index=0)

# Set all sheets
set_all_sheets_background("file.xmind", color="#FF0000FF")

# List sheets
sheets = list_sheets("file.xmind")

Command line:

uv run scripts/set_background.py file.xmind --color "#000000FF"
uv run scripts/set_background.py file.xmind --color "#FF0000FF" --all
uv run scripts/set_background.py file.xmind --list

File Structure

XMind files are ZIP archives containing:

• content.json - Main content (sheets, topics, structure)
• metadata.json - File metadata
• manifest.json - Package manifest
• Thumbnails/thumbnail.png - Preview image

content.json Structure

[
  {
    "id": "...",
    "title": "画布 1",
    "rootTopic": {
      "id": "...",
      "title": "中心主题",
      "children": {
        "attached": [
          {"id": "...", "title": "分支主题 1"},
          {"id": "...", "title": "分支主题 2"}
        ]
      }
    }
  }
]

JSONPath Expressions

Use JSONPath to locate topics in the mind map:

• $[0].rootTopic - First sheet's central topic
• $[0].rootTopic.children.attached[0] - First branch topic
• $[0].rootTopic.children.attached[?(@.title=="分支主题 1")] - Find by title

Dependencies

uv add jsonpath-ng

Template

A blank template is available at assets/demo.xmind.

Common Workflows

1. Create and Populate Mind Map

from scripts.create_xmind import create_xmind
from scripts.insert_topic import insert_topics_batch

# Create new file
create_xmind("project.xmind", sheet_title="Q1 Planning", root_topic_title="Goals")

# Add branch topics
insert_topics_batch(
    "project.xmind",
    "$[0].rootTopic",
    ["Marketing", "Development", "Sales"]
)

2. Modify Existing File

from scripts.xmind_utils import read_content, write_content

content = read_content("existing.xmind")
# Modify content directly
content[0]['title'] = "New Title"
write_content("existing.xmind", content, output_path="modified.xmind")

3. Batch Process Multiple Files

from pathlib import Path
from scripts.set_background import set_all_sheets_background

for xmind_file in Path("mindmaps/").glob("*.xmind"):
    set_all_sheets_background(xmind_file, color="#000000FF")

Topic Structure

When creating topics programmatically:

{
    "id": "uuid-here",
    "title": "Topic Name",
    "titleUnedited": True,
    "children": {
        "attached": [
            # Child topics here
        ]
    }
}

Best Practices

1. Always use output_path to avoid overwriting original files during development
2. Validate JSONPath expressions with --list-topics first
3. Quote color values in shell commands: "#000000FF" not #000000FF
4. Use UUIDs for new topic IDs (auto-generated by scripts)
5. Keep backups when batch processing

Error Handling

Common errors and solutions:

• FileNotFoundError: Check file path exists
• ValueError: 不是有效的xmind文件: File is corrupted or not a ZIP
• IndexError: sheet_index超出范围: Requested sheet doesn't exist
• ModuleNotFoundError: jsonpath_ng: Run uv add jsonpath-ng