repository·master·Indexed 41 days ago
https://github.com/tobyqin/xmindparserA Python library and CLI tool used to parse Xmind files (including Xmind 8, Zen, and 2026) into programmable data types such as dictionaries, JSON, XML, YAML, or Markdown. It provides functions like xmind_to_dict and xmind_to_file to convert XMind structures into various formats, with specific support for extracting internal JSON from Zen/2026 versions.
Install the package using pip to convert Xmind files to programmable data types like JSON, XML, or YAML. Requires Python 3.x.
Note: To parse into xml or yaml formats, you must install additional dependencies:
dicttoxmlpyyamlpip install xmindparserNew versions are published to PyPI automatically via GitHub Actions when a new version tag is pushed to GitHub.
Follow these steps to release a new version:
setup.py and CHANGELOG.md.vX.Y.Z format.Once the tag is pushed, GitHub Actions will automatically run tests (on Python 3.9-3.13), build the package, publish it to PyPI, and create a GitHub Release with the source distribution.
Requirement: The repository must have a PYPI_API_TOKEN secret configured in its settings.
git tag v1.1.0
git push origin v1.1.0You can customize the parsing behavior using the config object.
Important Lifecycle Rule:
logName, logLevel, logFormat), you must call apply_config() after modification for changes to take effect.showTopicId, hideEmptyValue, showStructure, showRelationship), changes take effect immediately.Available Configuration Keys:
logName: Logging filename.logLevel: Logging level (e.g., logging.DEBUG).logFormat: Logging string format.showTopicId: Include internal topic IDs (default: False).hideEmptyValue: Hide empty values (default: True).showStructure: Include structure info for sheets (default: True).showRelationship: Include relationship info for Zen/2026 files (default: False).import logging
from xmindparser import xmind_to_dict, config, apply_config
# Modify config settings
config['logName'] = 'your_log_name'
config['logLevel'] = logging.DEBUG
config['logFormat'] = '%(asctime)s %(levelname)-8s: %(message)s'
config['showTopicId'] = True
config['hideEmptyValue'] = False
config['showStructure'] = False
config['showRelationship'] = True
# Apply the config changes (required for logging settings)
apply_config()
d = xmind_to_dict('/path/to/your/xmind')The doc/example.md file serves as a representation of how xmindparser interprets XMind files. It demonstrates how different XMind elements are mapped to Markdown syntax:
# Sheet 1).##, ###, ####, etc.).> this is a note).**Comments:** section followed by a list of user/comment pairs.**Labels:** text.[Attachment]test.txt or [Image].[Link](url).测试, 中文测试).# Sheet 1
## test
### a
[Link](http://test.com)
#### e
##### f
###### g
#### d
#### e
> this is a note
##### h
**Comments:**
- **toby.qin**: this a comments
### b
#### types
##### comment
**Comments:**
- **toby.qin**: comment1
- **toby.qin**: comment2
- **toby.qin**: comment3
##### note
> 1 line note
###### note2
> line1
> line2
###### note3
> note with style
> line with strike
##### label
**Labels:** this is a label
##### attachment
###### [Attachment]test.txt
##### pic
###### [Image]
##### links
###### to url
[Link](http://test.com)
###### to file
[Link](file:////abc/ef)
###### to topic
#### 测试
##### note
> 测试中文
##### comments
**Comments:**
- **toby.qin**: 中文测试
#### </>{}[]*+-
### c
#### a
#### a
#### a
# Sheet 2
## test2
### a
#### 1
#### 2
#### 3
### bXmind Zen and 2026 versions use content.json as their internal data file. While xmind_to_dict works for general parsing, you can use the get_xmind_zen_builtin_json shortcut to extract the raw internal JSON content directly.
from xmindparser import get_xmind_zen_builtin_json
content_json = get_xmind_zen_builtin_json(xmind_zen_file)Use xmind_to_dict to parse an Xmind file into a Python dictionary (JSON-like structure).
from xmindparser import xmind_to_dict
d = xmind_to_dict('/path/to/your/xmind')
print(d)Use xmind_to_dict to parse an Xmind file into a programmable Python dictionary (JSON-like structure). This function automatically detects whether the file is from Xmind 8 or newer versions like Xmind Zen/2026.
from xmindparser import xmind_to_dict
d = xmind_to_dict('/path/to/your/xmind')
print(d)There are two ways to convert an Xmind file to a Markdown file in Python:
xmind_to_markdown: A specialized function that returns the path to the generated file.xmind_to_file: A generic function where you specify the target format as a string.from xmindparser import xmind_to_markdown, xmind_to_file
# Method 1: Specialized function
output_file = xmind_to_markdown('/path/to/your/xmind')
print(f'Generated: {output_file}')
# Method 2: Generic function
output_file = xmind_to_file('/path/to/your/xmind', 'markdown')
print(f'Generated: {output_file}')When parsing Xmind 8 files, the following features are not supported or have limited support:
showRelationship is enabled for Zen/2026)[Attachment] - name)[Image])When parsing legacy Xmind 8 files, the following features are not supported or only partially supported:
showRelationship=True).[Attachment] - name) and Images (parsed only as [Image]).You can parse Xmind files directly from the terminal to various formats using the xmindparser CLI.
Required dependencies for specific formats:
dicttoxml package.pyyaml package.Available commands:
# Convert to JSON
xmindparser your.xmind -json
# Convert to XML
xmindparser your.xmind -xml
# Convert to YAML
xmindparser your.xmind -yaml
# Convert to Markdown
xmindparser your.xmind -markdownThe xmind_to_file function is the primary entry point for converting an XMind file into a specific file format. It takes the path to the XMind file and a string representing the desired output type.
Parameters:
xmind: Path to the .xmind file.out_types: A string indicating the output format (e.g., 'json', 'xml', 'markdown').Returns the path to the generated file.
from xmindparser import xmind_to_file
# Example: Convert to markdown
output_path = xmind_to_file('path/to/my.xmind', 'markdown')
print(f'Generated: {output_path}')