README file from
GithubXMind Open
English | 中文
Show .xmind files in Obsidian's file explorer, preview them inline, and open them in the system default application — without ever parsing the mindmap.
The problem
Obsidian only lists a file in the file explorer when its extension is registered in the view registry:
isSupportedFile(file) =
vault.getConfig('showUnsupportedFiles') || viewRegistry.isExtensionRegistered(file.extension);
.xmind is not one of the built-in extensions, so your mindmaps are invisible in the vault — in the file explorer, the quick switcher and search alike.
Installing a mindmap plugin does not necessarily fix this. A plugin may register a view for a file type without registering the extension, and those are two different things.
What this plugin does
| Shows | .xmind files appear in the file explorer with an xmind tag |
| Previews | Renders the map preview XMind stores inside the archive |
| Opens | Hands the file to your operating system, so XMind starts as usual |
| Never | Parses, reads, or modifies the mindmap data |
Installation
Manual
- Download or clone this repository.
- Copy the folder into
<your vault>/.obsidian/plugins/xmind-open/. - In Obsidian, reload the plugins list (Settings → Community plugins), then enable XMind Open.
Desktop only (Windows, macOS, Linux). Opening a file in an external application is not available on mobile.
Usage
Click any .xmind file. A tab opens with the map preview and an Open with system default app button.
You can also right-click the file in the explorer and pick Open with system default app from the context menu.
Settings
| Setting | Default | Description |
|---|---|---|
| Open with the system app automatically | off | Off, the tab shows the preview and waits for a click. On, opening a file launches the system application immediately. |
| Show preview image | on | Renders the preview image stored inside the archive. |
| XMind executable path | (empty) | Leave empty to use the OS file association. Set a path only if that association is missing or has been taken over by another program. |
About the executable path
By default the plugin never looks for XMind. It hands the file to the operating system, which resolves .xmind through its own file association — so the plugin works regardless of where XMind is installed, and needs no configuration.
That design has one failure mode: if nothing is associated with .xmind, or another program has claimed it, opening does nothing useful. For those cases the settings accept an explicit path, and the Auto-detect button will look for it by:
- reading the current
.xmindassociation from the registry (HKCR\.xmind→shell\open\command), then - checking the usual install locations (
%ProgramFiles%,%ProgramFiles(x86)%,%LOCALAPPDATA%, …).
A detected path is only accepted if the file actually exists, so a stale registry entry is never adopted.
When a path is configured it takes priority, and a failure to launch reports the reason instead of silently falling back — otherwise a broken configuration would look like it worked.
How the preview works
An .xmind file is a plain ZIP archive, and XMind stores a pre-rendered image of the map at Thumbnails/thumbnail.png. Showing it therefore requires reading one entry out of a ZIP — not understanding the XMind document format. The mindmap data (content.json) is never opened.
The plugin ships a small ZIP reader (locate the End Of Central Directory, walk the central directory, inflate the single deflate entry) rather than bundling a library, since the plugin is a single file with no build step.
Everything degrades quietly. A missing preview entry, a corrupted archive, or an oversized image simply means no picture this time — the file still opens normally.
Permissions and system access
To do its job the plugin touches a few things outside your vault. They are listed here rather than buried in the settings.
| What | Why |
|---|---|
Reads Thumbnails/thumbnail.png from the .xmind file you open |
That is the preview image XMind itself stores. Nothing else inside the archive is read. |
| Resolves the absolute path of that file | The operating system needs a real path before it can open anything. |
Launches the application associated with .xmind |
This is the plugin's main action — opening your mindmap in XMind. |
| Optionally launches one specific executable that you configure | Only if you fill in XMind executable path. Leave it empty and the plugin never runs anything you did not ask for. |
It does not walk directories, does not read other files inside or outside your vault, and does not upload anything anywhere.
Privacy
- No network requests, ever.
- Nothing is written to your vault.
- From each
.xmindfile you open, exactly one entry (Thumbnails/thumbnail.png) is read, and the decoded result is cached in memory only, keyed by path and modification time.
Language
The interface follows Obsidian's own language setting: Chinese for a Chinese UI, English for everything else.
Development
The plugin is a single CommonJS file with no build step. main.js is the only entry point Obsidian loads.
An offline test suite lives in tests/. It runs the real plugin code against a stubbed obsidian module and a jsdom document, so no Obsidian installation is needed:
# 88 assertions: extension registration, the view, the opening chain,
# thumbnail extraction, custom-path handling and localisation
node tests/run-tests.js
# 20 mutants: each one deliberately breaks a behaviour, and the suite
# must fail — otherwise the corresponding test proves nothing
node tests/mutate.js
# cross-check the ZIP reader against a real .xmind file, comparing the
# extracted bytes with Python's zipfile
node tests/verify-thumbnail.js /path/to/file.xmind
npm install pulls in jsdom, the only development dependency — the plugin itself ships with none.
License
MIT — see LICENSE.