# Chx MindMap

English | [简体中文](README.zh-CN.md)

Chx MindMap is an independent, MIT-licensed mind map editor for **desktop Obsidian 1.14.4 or later**. Create and edit maps locally, switch between map, outline and table views, and import or export common formats. The plugin interface is currently **Chinese**; this guide includes the labels you will see.

Core features are free and require no Chx MindMap account or subscription. Optional AI generation connects to a service you choose, which may require a separate account and payment.

**Version:** this source revision is **1.0.3**, addressing the blocking review findings in 1.0.2. Available downloads are listed on [GitHub Releases](https://github.com/chxcode/obsidian-chx-mindmap/releases); application-store installation depends on the current [community review](https://community.obsidian.md/plugins/chx-mindmap). See the [remediation record](docs/review-remediation.md). Mobile is not supported.

## Installation

Until community review is complete, install manually:

1. Open [GitHub Releases](https://github.com/chxcode/obsidian-chx-mindmap/releases) and download `main.js`, `manifest.json` and `styles.css` from **the same release**. Starting with the 1.0.3 release workflow, these are the only uploaded release assets. Preserve the license notices embedded in `main.js`.
2. Open your vault's configuration directory. The default is `.obsidian/`; if you use a custom configuration directory, use that instead.
3. Create `plugins/chx-mindmap/` inside it. Place the three files directly in that folder. With the default configuration, the result must be `.obsidian/plugins/chx-mindmap/main.js`, alongside `manifest.json` and `styles.css`.
4. Restart Obsidian. In **Settings → Community plugins**, enable community plugins if needed, then enable **Chx MindMap**.
5. Open the command palette, search for **Chx MindMap**, and run **新建思维导图** (New mind map).

The plugin ID is `chx-mindmap`. New files use the `.chxmap` extension and are saved in the vault's `ChxMindMap/` folder by default. Back up important maps before trying a new release. Keep native `.chxmap` files for complete backups.

## Getting started

1. Create a map with **新建思维导图**. Double-click a node to edit its text.
2. Press `Tab` to add a child, or `Enter` to add a sibling. You can also use the toolbar. If no node is selected, the add actions use the central node. Drag nodes to change their position in the hierarchy.
3. Use the top toolbar to choose a layout or theme and switch between **导图** (map), **大纲** (outline) and **表格** (table).
4. Select a node and open **属性** (Properties) to change its appearance, add a note or link, or choose a local image.
5. Click **保存** (Save) to commit the current text immediately. Close and reopen the `.chxmap` file to continue editing.

Automatic saving normally runs 800 ms after a change; the delay is configurable. While a node text editor is open, background saving waits and shows **文字编辑中** (Editing text). It does not close the text editor or report uncommitted text as saved. Finish text editing to resume automatic saving, or use **保存** to commit and save immediately.

## Features and commands

- **Editing:** rich text, LaTeX formulas, node colors, fonts, shapes, images, note links, notes, descriptions, tags, markers, checkboxes, numbering, summaries, relationship lines and outer frames. A rich-text toolbar appears during text editing.
- **Views:** 14 engine layouts, seven custom color themes, editable outlines and tables, search/replace, a minimap and undo/redo. Fonts must be available on your computer.
- **Branch focus:** **聚焦此分支** edits one branch with a separate undo history. Use **退出分支聚焦** to return to the full map.
- **Presentation:** **演示** uses the left/right arrow keys to move through nodes; `Esc` exits. **填空** hides underlined text, which can be revealed by hovering or using presentation controls. **专注** hides toolbars; `Esc` returns.
- **Free trees:** **＋ 自由树** adds an independent tree card. Drag its title to move it, resize its lower-right corner, and select its own layout. A document supports up to 16 free trees; free trees cannot contain further free trees.
- **Import into a branch:** toolbar **导入** inserts a selected file beneath the current node. The command **导入为新的思维导图** imports as a new map and leaves the source file intact.
- **Editable Markdown embed:** **在当前笔记插入可编辑导图代码块** inserts a `chxmap` code block. Edit it in Reading view; changes are written back to the note. Drag the block to adjust its height.
- **Markdown preview:** **以只读导图预览当前 Markdown** opens a read-only outline of the current Markdown note and refreshes when that note changes.
- **Static preview:** **将当前导图保存为库内静态 PNG 预览** saves a PNG in the vault and offers a `![[...png]]` link to copy. Re-export it after editing the map to refresh the snapshot.

## File formats and limitations

The native `.chxmap` format is versioned JSON containing layouts, styles, node metadata and free trees. Native JSON/SMM export is also suitable for retaining the document's map data.

| Operation | Formats |
| --- | --- |
| Import | `.chxmap`, JSON, SMM, SimpleMindMap `.smm.md`, Markdown, TXT outlines, old/new XMind, FreeMind, OPML and XLSX |
| Export | PNG, JPG, SVG, PDF with clickable node links, JSON/SMM, Markdown, TXT, XMind, FreeMind, OPML, XLSX, DOCX, Mermaid and HTML |

Import also accepts the `.mindweave` JSON format used by this project's **early private development build**. This does not imply compatibility with blktree's MindWeave plugin or its files.

Cross-format export is a structural conversion, not a lossless backup. Tree structure, text, notes, links and tags are the main portable content. Images, special styling, summaries and relationship lines may not survive a round trip through another format. XLSX import reads the first worksheet's outline and cached values; it does not execute formulas. DOCX, HTML and spreadsheet exports are outline presentations.

Image, SVG and PDF export operate on the current tree. Export free trees from their own toolbars; native documents retain all trees together. Remote images are not rendered by default and will not appear in image exports. Use local PNG, JPEG, WebP or GIF images when possible. Vault image paths in imported SimpleMindMap files are not automatically migrated or packaged.

Imports have limits on file size, nesting, node count and expanded archive size. Rendering filters unsafe HTML and URLs, while unchanged original fields can remain in native documents. Complex formulas, unusual fonts, large maps and cross-platform appearance need more validation. Note links can open vault notes, but the plugin does not provide a complete Obsidian backlink index or full-vault content search.

## Saving, conflicts and local history

Normal file switching and view closing commit the active text edit and wait for saving; exports also commit the current input. Forced termination or a system crash can interrupt the last asynchronous write.

Before writing, the plugin atomically compares the file with the expected disk content. If an external change is detected, it leaves that file unchanged, creates a `.conflict-<timestamp>.chxmap` copy, and locks the view. Use **重新载入当前思维导图（冲突后使用）** (Reload current map after a conflict) to continue.

Local history retains up to 20 snapshots and approximately 20 MiB of document text per file under the plugin's `history/` directory. History is indexed by file path and does not automatically follow a renamed file. Back up that directory before uninstalling if you need to keep its history. History and conflict copies are local data, not encrypted backups.

## Privacy, network access and optional AI

Core editing, conversion, saving and history run locally. The plugin includes no analytics, telemetry or advertising, and does not read credentials saved by other plugins. Your existing vault synchronization or backup service may still handle these local files.

AI generation is optional. The default endpoint is `https://api.openai.com/v1`, and you may configure another OpenAI-compatible service. A request is made only after you click **AI 生成分支** (Generate branch with AI) and submit a topic. The plugin sends an HTTP POST to the configured `/chat/completions` endpoint containing:

- The topic you entered and the selected model name, which defaults to `gpt-4.1-mini`.
- A fixed system instruction requesting a Markdown mind-map outline, plus `temperature: 0.5`.
- Your session API key in an `Authorization: Bearer …` header, if you supplied one.

The current note, complete map and history are not automatically attached. Endpoint and model settings are saved locally; the API key is kept only in memory for the current plugin session and must be entered again after reloading. Use HTTPS for remote services. The provider receives the request and ordinary connection information such as your IP address. Its own data policy applies, and it may require an account, key and usage charges. Live AI service requests have not been tested end to end.

Selecting an import file or local image reads the selected file, which may be outside the vault. Explicit exports save through the local download mechanism; the application or system determines the destination. Static PNG previews are written to the vault. Copy, cut, paste and **复制链接** (Copy link) actions access the system clipboard. Clicking an external node link opens its website or application. The note picker lists vault notes to help you create a link. See the [privacy details](PRIVACY.md) for storage and deletion information.

## Validation and known limits

The **1.0.3** revision passed 89 Node tests, TypeScript checks, source linting (0 errors; 766 advisory warnings), release-asset/license checks and 26 real-browser editor checks. New checks cover safe rich-text and SVG fragment rendering, CSS cursor behavior, and browser ZIP/DOCX execution with string-code generation disabled. Archive expansion and malformed-size limits remain tested. These are local/CI checks, not a claim that the community review passed.

The earlier **1.0.2** passed 82 Node tests and 23 browser checks. Native Obsidian installation, Chinese editing, save/reopen, undo/redo and PNG export were checked only on the early **private 1.0.1** build; those results are not native verification of 1.0.3.

Complex multi-window lifecycles, cross-device synchronization races, all advanced native integrations, large-map performance and live AI requests are not comprehensively validated. Mobile is unsupported. The [validation record](docs/validation.md) includes the browser startup issue observed before the final successful run and separates historical evidence from current results.

The production dependency audit (`npm audit --omit=dev`) has **two low-severity package entries for one Quill advisory** and reported no moderate, high or critical entries in that scan. The code does not call the advisory's affected HTML-export API, but this is not a guarantee of zero vulnerabilities. See the [dependency security review](docs/dependency-security.md). Report vulnerabilities using [SECURITY.md](SECURITY.md).

## Build from source

```sh
npm ci --ignore-scripts
npm test
npm run typecheck
npm run lint
npm run build
npm run check:release
```

Plugin assets are written to `dist/`. To build and serve the browser checks locally:

```sh
npm run build:browser
python3 -m http.server 8000 --bind 127.0.0.1
```

Open `http://127.0.0.1:8000/tests/browser.html`. See the [release guide](docs/releasing.md) for packaging and community submission. For bugs or suggestions, use [GitHub Issues](https://github.com/chxcode/obsidian-chx-mindmap/issues) with synthetic examples rather than private notes.

## License, credits and independence

This project's own code is [MIT-licensed](LICENSE). Rendering uses the npm distribution of the MindMap Team's [simple-mind-map](https://github.com/wanglin2/mind-map), version `0.14.0-fix.3`, under MIT. Preserve the [third-party copyright and license notices](THIRD_PARTY_NOTICES.txt) when distributing the plugin.

The Obsidian integration, interface, format adapters and save coordination were independently implemented with AI-assisted development. Public SimpleMindMap feature descriptions were used as a requirements reference; see the [feature comparison](docs/feature-matrix.md) and [provenance record](docs/provenance.md). The project does not use the commercial plugin's proprietary code, assets, activation mechanisms or credentials, and does not claim complete commercial-plugin parity.

Chx MindMap is not affiliated with, endorsed by or partnered with Obsidian, SimpleMindMap, its commercial plugin authors, or other projects named MindWeave, including blktree's plugin.