The Mind Map

English | 中文

🧠 MindMap Studio

Mind map rendering for Markdown inside Obsidian. Open .mindmap.md — a normal Markdown file — and edit it as a mind map; the Markdown outline round-trips. Powered by the simple-mind-map engine, developed by WinterMosquito.

🚀 Quick start

1. Create: run Create new mind map (command palette or ribbon) — name it (default = prefix + date); the MindMap2026-09-06.mindmap.md file is created and opens as a mind map.
2. Edit: the file is ordinary Markdown, so its outline becomes the map — add/edit/delete nodes, drag to rearrange, attach images or links.
3. Back & save: use Switch to Markdown to return anytime; edits are written back to the file (layout & viewport live in the plugin's data.json).

---

✨ Why MindMap Studio

The plugin is a rendering layer, not a file-format converter. .mindmap.md files are 100% standard Markdown — your notes, links, backlinks, search and Git all work as usual. A Markdown outline is parsed into a mind map; when you edit the map, the changes are written back as Markdown.

🚀 Features

• Markdown-native: .mindmap.md is ordinary Markdown (headings + lists). No proprietary format.
• Round-trip fidelity: unedited lines are written back verbatim (frontmatter preserved; blank lines between paragraphs and standalone --- separators are normalised); headings #–###### map to node levels 1–6, nested lists to deeper levels.
• Obsidian-native wikilinks: [[note]] shows as its link text, with hover preview and graded modifier clicks (matching Obsidian): plain click = current tab, Ctrl/Command+click = new tab, +Alt = new tab group, plus Shift = new window; the add-link dialog searches notes and other documents (.canvas / .base) plus non-image vault files (attachments); images go through Add image. Links whose target does not exist yet render in a muted colour (like Obsidian's reading view), resolved by the plugin from Obsidian's metadata cache; hover/click is left to Obsidian core (no pre-check on that path). New document links follow Obsidian's own settings: with Use [[Wikilinks]] on (the official default) they are written as [[wikilinks]] (keeping the dedicated document icon); with it off they are written as [label](path.md), and the path form follows New link format. Attachments and images always keep the wikilink embed form (![[report.pdf]] / [[archive.zip]]). A node shows the alias (the note name when there is none); editing the text of a pure wikilink node edits that alias and writes back [[note|new alias]]. Attaching a wikilink — dropping a vault file (notes / images / attachments, any type) onto the node, or picking one in the add-link dialog — turns a completely empty node into a pure wikilink by writing the link's display name as its text; a node that already has any content (text, an image or an existing link — a pure-wikilink node included) keeps it, and the new link becomes a child node. A URL on its own node stays icon-only (no text).
• Rich node content (clickable links + inline syntax): links inside a node render as clickable text — click to open, Ctrl/Command+click for a new tab (+Alt for a new tab group, plus Shift for a new window); every link on a line is clickable (no longer only the first one). Hover preview has two levels: hovering a specific link text previews that link (important for multi-link lines and when the first link is an external URL), while hovering anywhere else on the node previews the link the node carries (vault targets only). A URL mixed with other content is shown as a clickable address instead of a bare icon. Inline syntax renders inside nodes the way Obsidian's reading view shows it: **bold** / __bold__, *italic* / _italic_, `inline code` (including double-backtick spans), ~~strikethrough~~, ==highlight==, ***bold italic***; \*escaped\* consumes the backslash and shows the literal character, and %%comments%% are hidden inside the node (kept in the file; a line that is nothing but a comment stays literal). The raw text stays verbatim in the file; links inside paragraph (multi-line) nodes are clickable too. Very long nodes (> 2000 chars) show the beginning plus … (with a hover explanation) — the full text stays in the file, which also keeps oversized text from slowing the canvas down. Double-clicking such a node edits the actual line from the file (wikilink, URL and inline syntax stay visible and editable).
• Images: vault image suggestions, uniform sizing, ![[path]] round-trip; drag the corner handle to resize a node image — the size is written back as Obsidian's official embed syntax (![[img.png|300]] width-only, |300x150 explicit, ![alt|300](https://raw.githubusercontent.com/wintermosquito/the-mind-map/HEAD/url) for external images); clear a node's text and the node becomes image-exclusive — an image-exclusive node has no text, so node search never matches it. Inline images also render in text/paragraph nodes (its first line; links inside a paragraph are clickable too, see above).
• Opens at 100% with the whole map centred; Fit to canvas zooms out for an overview and Reset zoom returns to 100% while keeping the visible content in place (auto-arrange ends with fit-to-canvas); six layouts (switching a layout auto-arranges and fits the map) with per-file connector styles (Auto follows the layout; curve / direct / elbow — switchable for Logical structure / Mind map / Organization chart; the other three are fixed-straight and show Auto), node search, auto-arrange, performance mode for large maps, PNG export; assisted drag reparenting — drop near a node's center to nest as its child, or between two siblings to insert in between (with live highlight).
• Persistence: layout, viewport and "open as" preference are kept per file (in plugin data), surviving reopen, rename, and view switching.
• Central node ↔ filename: editing the central node renames the .mindmap.md file (Obsidian updates links/backlinks).

📖 Usage

1) Create & open a mind map

• Run Create new mind map (command palette or ribbon) → a naming dialog appears (default = prefix + date; duplicates get a numeric suffix) → the MindMap2026-09-06.mindmap.md file is created and opens in the mind-map view.
• Any .mindmap.md file opens from its context menu → Open as mind map (or the same command), and goes back via Open as Markdown. The view you chose is remembered.
• The command palette also lists Create mind map in current folder, Search nodes, Fit to canvas, Arrange mind map and Export as PNG — the same actions as the toolbar.

2) How Markdown becomes a map

Every .mindmap.md is 100% standard Markdown — the plugin renders it as a mind map and writes your edits back:

# Project plan              ← central node (= file name)
## Goals                    ← first-level child node (#)
- Milestone 1               ← child node (list)
- Milestone 2
###### Details              ← level-6 heading
- Seventh-level item        ← list nested under a heading → level 7

#–###### → node levels 1–6 · nested lists go deeper · [[note]] / [[note|alias]] → clickable link (the node shows the alias) · bare URLs → clickable address · inline syntax renders inside nodes (**bold** / __bold__, *italic* / _italic_, `inline code`, ~~strikethrough~~, ==highlight==, ***bold italic***; \*escaped\* shows literally and %%comments%% are hidden — a comment-only line stays literal) · ![[img]] → image (|300 sets the size) · paragraphs & fenced code stay as text (links inside paragraphs are clickable too).

Non-image embeds such as ![[report.pdf]] on a node of their own are shown as an attachment icon: click the icon, or Ctrl/Command+click the node, to open it (PDF, audio, video); hovering the node triggers Obsidian's native preview as well. Mixed with other descriptive text, they render as a clickable text link instead. Neither is rendered inline — a mind-map node cannot host Obsidian's inline media view.

Files dragged in from your system (images / PDFs / audio & video / notes / any other file) need a selected node first (a notice appears otherwise): they are copied into the "default location for new attachments" and attached to that node (embeddable types are written as embeds ![[report.pdf]], everything else as links [[archive.zip]]); holding Ctrl (Windows/Linux) / Option (macOS) instead skips the copy and inserts an absolute link to the original location [file name](file:///…) (wrapped in <…> only when the path contains spaces or brackets; clicking opens it in your system's default app) — the same behaviour as Obsidian's drag & drop.

3) Everyday actions (in the mind-map view)

4) Saving & persistence

• Unedited lines are written back verbatim (frontmatter preserved; blank lines between paragraphs and standalone --- separators are normalised); editing a pure wikilink node (the whole line is one wikilink) edits its alias, written back as [[note|new alias]] (clearing the text drops the alias and keeps the link; nodes that mix text and a link still round-trip as "text + link").
• Layout, viewport and "open as" are kept per file in the plugin data.json; node image sizes go into the note itself as official embed syntax (![[img|300]]).
• Editing the central node renames the .mindmap.md (Obsidian updates links/backlinks).
• Config is local; no telemetry, and the plugin makes no network requests — nothing is sent anywhere.
• Files outside the vault are only ever touched when you ask for it: an absolute file:/// link (created by holding Ctrl/Option while dropping a file) is handed to your system's default app when you click it. The plugin does not read, copy or upload those files.

5) Deliberate differences from Obsidian

The mind-map view is a third kind of view (neither reading nor editing view), so a few interactions follow this view's semantics. All of them are registered (see AGENTS.md K56 ⑤):

The full Markdown ↔ mind-map mapping rules live in docs/markdown-mindmap-standard.md.

📦 Install

• Community plugins (once listed): Settings → Community plugins → search MindMap Studio.
• From GitHub releases (recommended): download the latest release assets (main.js, manifest.json, styles.css) from the repo Releases page, copy them into <vault>/.obsidian/plugins/mindmap-studio/, reload Obsidian, then enable the plugin in Settings → Community plugins.
• Build from source: npm install && npm run build produces main.js; copy it together with manifest.json and styles.css into the plugin folder.

Requires Obsidian 1.13.0 or later. Desktop only (Windows, macOS, Linux). Config is stored locally (plugin data.json); no telemetry and no network requests. main.js is built in CI and attached to each GitHub Release (it is not committed to the repo).

🛠 Development

npm install
npm run dev      # watch mode
npm run build    # type-check + production bundle (main.js)
npm test         # regression suite (vitest)
npm run lint     # ESLint (the official obsidianmd ruleset, warnings are errors)
npm run lint:css # stylesheet rules — mirrors the community-directory scanner's stylelint set
npm run check:release   # release metadata guard (versions.json / manifest / README)
npm run verify:visual   # headless-Chrome render & contract checks (add `-- --perf` for a real-clock baseline)

The engine (vendor/simple-mind-map.cjs) is vendored and must not be hand-edited; rebuild from upstream source when upgrading. Bundled third-party licences are listed in vendor/THIRD-PARTY-NOTICES.md.

⚖️ License

MIT — see the LICENSE file in the repository root. The plugin bundles the simple-mind-map engine and its dependencies under their own licences (MIT / BSD-3-Clause); those notices live in vendor/THIRD-PARTY-NOTICES.md.