obsidian-plugin/ninglg_light-mindmap
1
0
Fork 0
mirror of https://github.com/ninglg/light-mindmap.git synced 2026-07-22 17:10:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
ninglg_light-mindmap/README.md
Lywooye 733efdb152 Add node drag and keyboard restructuring
2026-06-28 01:14:49 -07:00

532 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Light Mindmap
**English** | [简体中文](#License)
Feature-rich mindmap plugin — multiple layouts, themes, node shapes & line styles, wikilink support, node collapse, PNG export — all from plain Markdown headings and nested lists, no custom syntax needed.
**Key feature:** supports mindmaps deeper than six levels and three Markdown structure modes: heading-only, hybrid headings plus lists, and pure nested lists.
## What's New in This Version
- **More than six levels:** deep mindmaps can continue past Markdown's six heading levels.
- **Three structure modes:** choose **Heading**, **Hybrid**, or **List** from the toolbar.
- **Automatic format detection:** converting an existing Markdown note detects heading-only, heading-plus-list, or list-only structure and writes `mindmap-structure`.
- **Editable source compatibility:** canvas edits are written back using the selected Markdown structure mode.
- **Drag and keyboard restructuring:** move nodes by dragging, reorder siblings with `Shift + ArrowUp/ArrowDown`, promote with `Shift + Tab` or `Mod + ArrowLeft`, and demote with `Mod + ArrowRight`.
- **Safer mode switching:** heading mode is blocked for maps deeper than six levels, because Markdown headings cannot represent that depth.
## Preview
![Light MindMap Preview](preview.png)
## How It Works
Add `type: mindmap` to any note's frontmatter. The plugin replaces the editor/reading view with a live mind map built from the note's Markdown structure. Use the toolbar **Mode** dropdown to choose **Heading**, **Hybrid**, or **List** mode. Hybrid mode stores levels 1-6 as headings and deeper nodes as nested list items.
You can also right-click a folder in the file explorer and select **Create light mindmap** to quickly create a new mindmap file in that folder.
To convert an existing Markdown note, click the ribbon **Convert current note to mindmap** button, run the same command from the command palette, or right-click a Markdown file and choose **Convert to light mindmap**. The command adds the required `type: mindmap` frontmatter and default display settings without rewriting the note body. It also detects whether the note is heading-only, heading plus list, or list-only, then writes the matching `mindmap-structure` value.
```yaml
---
type: mindmap
mindmap-structure: hybrid
---
# My Plan
## Life
### walk the dog
### cook dinner
### call my parents
## *Work*
### write report
### team discussion
### send emails
## *Study*
### learn new words
### listen to podcast
### practice coding
## Shopping
### buy fruits
### get stationery
### pick up snacks
###### detailed checklist
- compare prices
- local store
- online store
```
The mind map updates in real time as you edit the source.
## Features
### Auto-Render from Selectable Structure Modes
- Toolbar **Mode** dropdown switches between `heading`, `hybrid`, and `list` structure modes
- `heading` mode parses Markdown headings (`#` through `######`) only
- `hybrid` mode parses headings plus nested list items, so structures can continue beyond six heading levels
- `list` mode parses nested Markdown list items only
- Provides a one-click conversion button/command for existing Markdown notes and auto-detects the structure mode
- Strips inline markdown (bold, italic, links, wikilinks, code) from node labels
- When multiple top-level headings exist, a virtual root node (named after the file) is created automatically
- Fenced code blocks are skipped during parsing
### Structure Modes
| Mode | Source format | Best for |
| ---- | ------------- | -------- |
| **Heading** | Markdown headings only | Short maps that should stay as ordinary document outlines |
| **Hybrid** | Headings for levels 1-6, nested lists for deeper nodes | Deep maps that still need readable document sections |
| **List** | Nested Markdown lists only | Mobile-friendly outlining and fast indentation editing |
The selected mode is saved in frontmatter as `mindmap-structure`. If the key is missing, the plugin scans the note body and chooses `hybrid` for heading plus list documents, `list` for list-only documents, and `heading` for heading-only documents.
### Deep Mindmaps with Lists
Markdown only defines six heading levels. For deeper mindmaps, continue the hierarchy with nested Markdown lists after a heading:
```markdown
# Root
## Branch
### Level 3
#### Level 4
##### Level 5
###### Level 6
- Level 7
- Level 8
- Level 9
```
Canvas node edits are still written back to the source note. Levels 1-6 are serialized as headings, and deeper levels are serialized as nested list items.
### Layouts
Five layout modes, switchable from the toolbar dropdown or via command:
| Layout | Description |
| ---------------- | ------------------------------------------------------------------------------ |
| **Balanced** | Children are distributed to both sides of the root, weighted by subtree height |
| **Right** | All branches expand to the right |
| **Left** | All branches expand to the left |
| **Tree** | Top-down tree — root at the top, branches expand downward |
| **Radial** | Root at the center, branches radiate outward in a circle |
### Themes
Seven built-in color palettes:
| Theme | Style |
| ------------ | --------------------------------------------- |
| **Vibrant** | Indigo/violet/pink gradient — the default |
| **Classic** | Earth tones on a warm cream background |
| **Fresh** | Greens and teals on a light mint background |
| **Ocean** | Blues and indigos on a pale blue background |
| **Sunset** | Reds, oranges, and pinks on a warm background |
| **Midnight** | Neon accents on a dark slate background |
| **Slate** | Cool blue-grey with a subtle tech grid pattern |
Themes adapt automatically to Obsidian's dark/light mode.
### Connection Line Styles
| Style | Shape | Dash |
| ---------------------- | ------------------------------ | ------ |
| **Smooth** | Cubic Bézier curve | Solid |
| **Smooth Dashed** | Cubic Bézier curve | Dashed |
| **Straight** | Direct line | Solid |
| **Right Angle** | Horizontal + vertical segments | Solid |
| **Right Angle Dashed** | Horizontal + vertical segments | Dashed |
### Node Shapes
| Shape | Appearance |
| -------------- | ------------------------------------- |
| **Rounded** | Rounded rectangle (default) |
| **Square** | Sharp corners |
| **Borderless** | No border or background on leaf nodes |
| **Pill** | Fully rounded capsule |
| **Doodle** | Hand-drawn style with slight rotation |
### Pan & Zoom
- **Drag** the canvas background to pan (mouse or touch)
- **Pinch** to zoom on touch devices
- **Scroll** to pan vertically/horizontally
- **Ctrl/Cmd + Scroll** to zoom in/out around the cursor
- Toolbar buttons: **Fit** (fit all nodes into view), **+** / **−** (step zoom)
### Node Editing
Nodes can be edited directly on the canvas — changes are written back to the markdown file:
| Action | Gesture / Key |
| ----------------------------- | ---------------------------------------------- |
| Select node | Click |
| Edit node text | Double-click or **F2** |
| Confirm edit | **Enter** |
| Confirm edit + add child | **Tab** |
| Cancel edit | **Escape** |
| Add sibling (without editing) | Select node, press **Enter** |
| Add child (without editing) | Select node, press **Tab** |
| Delete node | Select node, press **Delete** or **Backspace** |
| Collapse / expand node | Select node, press **Space** |
| Move sibling up / down | Select node, press **Shift + ArrowUp / ArrowDown** |
| Promote node | Select node, press **Shift + Tab** or **Mod + ArrowLeft** |
| Demote under previous sibling | Select node, press **Mod + ArrowRight** |
| Drag node | Drag onto another node; top/bottom drops reorder, middle drops as child |
| Right-click context menu | Right-click on node |
- The root node cannot be deleted.
- Pressing **Enter** on the root node has no effect (no sibling can be added above root).
- Pressing **Tab** on a collapsed node auto-expands it and adds a new child.
- Double-clicking or pressing **F2** on a collapsed node auto-expands it and enters edit mode.
- Collapsed nodes display a **+** badge after the text. The badge is also rendered in exported PNGs.
### Right-Click Context Menu
Right-click on any node to open the context menu with quick actions:
| Action | Description |
| ---------------- | ----------------------------------------------------------- |
| **Edit** | Enter edit mode for the node |
| **Add Sibling** | Insert a sibling node (not available on root) |
| **Add Child** | Create a child node (auto-expands if collapsed) |
| **Collapse** | Toggle collapsed state (only for nodes with children) |
| **Delete** | Delete the node (not available on root) |
The context menu automatically displays in Chinese or English based on Obsidian's language setting.
### Persisted Settings
All per-file display preferences are written to frontmatter and restored on next open:
| Frontmatter key | Values |
| ---------------- | ---------------------------------------------------------------------- |
| `mindmap-structure` | `heading` / `hybrid` / `list` |
| `mindmap-layout` | `balanced` / `right` / `left` / `tree` / `radial` |
| `mindmap-theme` | `vibrant` / `classic` / `fresh` / `ocean` / `sunset` / `midnight` / `slate` |
| `mindmap-line` | `curve` / `straight` / `polyline` / `polyline-dashed` / `curve-dashed` |
| `mindmap-node` | `rounded` / `square` / `borderless` / `circle` / `doodle` |
### Toggle Source View
- **Edit Markdown** button in the toolbar hides the mind map and shows a floating **Light Mindmap** button
- Returning from source view auto-fits the mindmap to the viewport
- Command palette: **Toggle mindmap / source view**
- Command palette: **Cycle mindmap layout (balanced / right / left / tree / radial)**
### Links & Wiki-links
Markdown links (`[text](url)`) and wiki-links (`[[Note]]`, `[[Note|Alias]]`) in heading or list-item text are rendered as clickable links on the mindmap canvas.
- **External links** (`http://...`) open in the default browser
- **Internal links** (relative paths like `./note.md`) open in a new Obsidian tab
- **Wiki-links** (`[[Note]]`) open the target note in a new Obsidian tab — supports shortest paths, relative paths, and aliases natively
During node editing, typing `[[` triggers an autocomplete popup that searches all vault notes. Use **↑↓** to navigate, **Enter** to insert, **Escape** to dismiss. Links are shown as plain text while editing for easy modification.
### Export PNG
Click the **Export PNG** button in the toolbar to save the current mindmap as a high-resolution PNG image (2x scale). A system file dialog will let you choose the save location.
## Installation
### From Obsidian Community Plugins (recommended)
1. Open **Settings → Community plugins → Browse**
2. Search for **Light Mindmap**
3. Click **Install**, then **Enable**
### Manual
1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/ninglg/obsidian-light-mindmap/releases/latest)
2. Copy the three files into `<vault>/.obsidian/plugins/obsidian-light-mindmap/`
3. Reload Obsidian and enable the plugin in **Settings → Community plugins**
## Example Frontmatter
```yaml
---
type: mindmap
mindmap-structure: hybrid
mindmap-layout: balanced
mindmap-theme: vibrant
mindmap-line: curve
mindmap-node: rounded
---
```
## Compatibility
- Minimum Obsidian version: **1.4.0**
- Desktop and mobile supported
- Works with both light and dark Obsidian themes
## License
MIT
---
[English](#light-mindmap) | **简体中文**
功能丰富的思维导图插件——多种布局、主题、节点形状与连线样式，支持双向链接、节点折叠、PNG 导出——基于 Markdown 标题和嵌套列表渲染，无需任何自定义语法。
**主要特点：**支持超过 6 层的导图节点，并同时支持三种 Markdown 结构模式：纯标题、标题加列表、纯列表。
## 本版本新增
- **超过 6 层节点：**导图可以突破 Markdown 六级标题限制继续向下展开。
- **三种结构模式：**工具栏可直接选择 **Heading**、**Hybrid**、**List**。
- **自动识别格式：**把已有 Markdown 转为导图时，会自动识别纯标题、标题加列表、纯列表，并写入 `mindmap-structure`。
- **源文档可编辑同步：**在画布上编辑节点后，会按当前结构模式写回 Markdown。
- **拖拽和快捷键调整结构：**可拖拽节点改变位置和父级；`Shift + ArrowUp/ArrowDown` 调整同级顺序，`Shift + Tab` 或 `Mod + ArrowLeft` 提升一级，`Mod + ArrowRight` 降到上一个同级节点下面。
- **更安全的模式切换：**超过 6 层的导图不会被切到纯标题模式，避免 Markdown 表达不了深层结构。
## 预览
![Light MindMap 预览](preview.png)
## 使用方法
在笔记的 frontmatter 中添加 `type: mindmap`，插件会自动将编辑/阅读视图替换为实时思维导图，导图内容来自笔记的 Markdown 结构。可以在工具栏 **Mode** 下拉框中选择 **Heading**、**Hybrid** 或 **List** 模式；混合模式会把 1-6 层保存为标题，更深层节点保存为嵌套列表。
也可以在文件资源管理器中右键点击**文件夹**，选择 **新建轻量级脑图**，快速在该文件夹下创建一个新的脑图文件。
如果要转换已有 Markdown 笔记，可以点击左侧 ribbon 的 **Convert current note to mindmap** 按钮、从命令面板运行同名命令，或右键 Markdown 文件选择 **Convert to light mindmap**。该命令只会补上所需的 `type: mindmap` frontmatter 和默认显示设置，不会重写正文内容。它会自动识别笔记是纯标题、标题加列表，还是纯列表，并写入对应的 `mindmap-structure`。
```yaml
---
type: mindmap
mindmap-structure: hybrid
---
# My Plan
## Life
### walk the dog
### cook dinner
### call my parents
## *Work*
### write report
### team discussion
### send emails
## *Study*
### learn new words
### listen to podcast
### practice coding
## Shopping
### buy fruits
### get stationery
### pick up snacks
```
编辑源文件时，思维导图会实时更新。
## 功能特性
### 从可选结构模式自动生成导图
- 工具栏 **Mode** 下拉框可在 `heading`、`hybrid`、`list` 三种结构模式间切换
- `heading` 模式只解析 Markdown 标题（`#` 到 `######`）
- `hybrid` 模式解析标题和嵌套列表，使导图可以继续超过六层
- `list` 模式只解析嵌套 Markdown 列表
- 为已有 Markdown 笔记提供一键转换按钮/命令，并自动识别结构模式
- 自动去除节点文本中的行内 Markdown 格式（粗体、斜体、链接、Wiki 链接、行内代码）
- 当存在多个顶级标题时，会自动创建以文件名命名的虚拟根节点
- 解析时自动跳过围栏代码块
### 结构模式
| 模式 | 源格式 | 适合场景 |
| ---- | ------ | -------- |
| **Heading** | 只使用 Markdown 标题 | 层级较短、希望保留普通文档大纲的导图 |
| **Hybrid** | 1-6 层标题，更深层使用嵌套列表 | 深层导图，同时保留可读章节结构 |
| **List** | 只使用嵌套 Markdown 列表 | 手机端快速缩进编辑、移动端友好的大纲 |
选择结果会保存到 frontmatter 的 `mindmap-structure`。如果缺少该字段，插件会扫描正文：标题加列表识别为 `hybrid`，纯列表识别为 `list`，纯标题识别为 `heading`。
### 使用列表表达深层导图
Markdown 只定义了六级标题。对于更深的导图，可以在标题后继续使用嵌套列表：
```markdown
# Root
## Branch
### Level 3
#### Level 4
##### Level 5
###### Level 6
- Level 7
- Level 8
- Level 9
```
画布上的节点编辑仍会写回源笔记。第 1-6 层会保存为标题，更深层级会保存为嵌套列表项。
### 布局模式
五种布局，可通过工具栏下拉菜单或命令切换：
| 布局 | 说明 |
| ---------- | ---------------------------------------------- |
| **均衡** | 子节点分布于根节点两侧，按子树高度加权分配 |
| **向右** | 所有分支向右展开 |
| **向左** | 所有分支向左展开 |
| **树形** | 自上而下树状布局，根节点在顶部，分支向下展开 |
| **放射** | 根节点居中，分支沿圆周向外辐射 |
### 主题
七套内置配色方案：
| 主题 | 风格 |
| ---------- | ------------------------------------------ |
| **活力** | 靛蓝/紫罗兰/粉红渐变——默认主题 |
| **经典** | 暖色大地色调，奶油色背景 |
| **清新** | 绿色与青色，薄荷色背景 |
| **海洋** | 蓝色与靛色，浅蓝色背景 |
| **日落** | 红、橙、粉暖色调，温暖背景 |
| **午夜** | 深色底板搭配霓虹色彩 |
| **石板** | 冷灰蓝色调，带淡雅科技网格纹理 |
主题会自动适配 Obsidian 的深色/浅色模式。
### 连线样式
| 样式 | 形状 | 虚线 |
| ------------------ | ------------------ | ---- |
| **平滑** | 三阶贝塞尔曲线 | 实线 |
| **平滑虚线** | 三阶贝塞尔曲线 | 虚线 |
| **直线** | 直线段 | 实线 |
| **直角** | 水平 + 垂直折线 | 实线 |
| **直角虚线** | 水平 + 垂直折线 | 虚线 |
### 节点形状
| 形状 | 外观 |
| ---------- | ---------------------------- |
| **圆角** | 圆角矩形（默认） |
| **方角** | 直角矩形 |
| **无边框** | 叶子节点无边框和背景 |
| **胶囊** | 完全圆角的胶囊形 |
| **涂鸦** | 手绘风格，带轻微随机旋转 |
### 平移与缩放
- **拖拽** 画布背景进行平移（支持鼠标和触屏）
- **捏合** 进行触屏缩放
- **滚轮** 上下/左右平移
- **Ctrl/Cmd + 滚轮** 以光标为中心缩放
- 工具栏按钮：**适配**（将所有节点适配到视窗）、**+** / **−**（步进缩放）
### 节点编辑
可直接在画布上编辑节点，修改会回写到 Markdown 源文件：
| 操作 | 手势 / 按键 |
| -------------------------- | --------------------------------------- |
| 选中节点 | 单击 |
| 编辑节点文字 | 双击或按 **F2** |
| 确认编辑 | **Enter** |
| 确认编辑并添加子节点 | **Tab** |
| 取消编辑 | **Escape** |
| 添加同级节点（无需编辑） | 选中节点后按 **Enter** |
| 添加子节点（无需编辑） | 选中节点后按 **Tab** |
| 删除节点 | 选中节点后按 **Delete** 或 **Backspace**|
| 折叠/展开节点 | 选中节点后按 **Space** |
| 上下移动同级节点 | 选中节点后按 **Shift + ArrowUp / ArrowDown** |
| 提升节点层级 | 选中节点后按 **Shift + Tab** 或 **Mod + ArrowLeft** |
| 降到上一个同级节点下面 | 选中节点后按 **Mod + ArrowRight** |
| 拖拽节点 | 拖到目标节点上；上/下边缘表示前后排序，中间表示作为子节点 |
| 右键上下文菜单 | 右键点击节点 |
- 根节点不可删除。
- 在根节点上按 **Enter** 无效（根节点上方无法添加同级节点）。
- 在已折叠节点上按 **Tab** 会自动展开并添加子节点。
- 双击或按 **F2** 已折叠节点会自动展开并进入编辑模式。
- 已折叠节点的文字后会显示 **+** 标记，导出 PNG 时也会保留该标记。
### 右键上下文菜单
右键点击任意节点可打开上下文菜单，提供快捷操作：
| 操作 | 说明 |
| ---------------- | ------------------------------------------------------- |
| **编辑** | 进入节点编辑模式 |
| **创建同级节点** | 在当前节点同级插入新节点（根节点不可用） |
| **创建下级节点** | 创建子节点（已折叠时自动展开） |
| **折叠/展开** | 切换折叠状态（仅对有子节点的节点可用） |
| **删除** | 删除节点（根节点不可用） |
上下文菜单会根据 Obsidian 的语言设置自动显示中文或英文。
### 持久化设置
所有单文件显示偏好会写入 frontmatter，下次打开时自动恢复：
| Frontmatter 字段 | 可选值 |
| ------------------ | -------------------------------------------------------------------------- |
| `mindmap-structure`| `heading` / `hybrid` / `list` |
| `mindmap-layout` | `balanced` / `right` / `left` / `tree` / `radial` |
| `mindmap-theme` | `vibrant` / `classic` / `fresh` / `ocean` / `sunset` / `midnight` / `slate`|
| `mindmap-line` | `curve` / `straight` / `polyline` / `polyline-dashed` / `curve-dashed` |
| `mindmap-node` | `rounded` / `square` / `borderless` / `circle` / `doodle` |
### 切换源码视图
- 工具栏中的 **Edit Markdown** 按钮可隐藏思维导图并显示浮动的 **Light Mindmap** 按钮
- 从源码视图返回时会自动适配导图到视窗
- 命令面板：**Toggle mindmap / source view**
- 命令面板：**Cycle mindmap layout (balanced / right / left / tree / radial)**
### 链接与双向链接
标题或列表项中的 Markdown 链接（`[文本](url)`）和 Wiki 链接（`[[笔记]]`、`[[笔记|别名]]`）会直接在思维导图画布上渲染为可点击的链接。
- **外部链接**（`http://...`）在默认浏览器中打开
- **内部链接**（相对路径如 `./note.md`）在新的 Obsidian 标签页中打开
- **Wiki 链接**（`[[笔记]]`）在新的 Obsidian 标签页中打开目标笔记——原生支持最短路径、相对路径和别名
编辑节点时，输入 `[[` 会触发自动补全弹窗，搜索所有 vault 笔记。使用 **↑↓** 导航、**Enter** 插入、**Escape** 关闭。编辑模式下链接显示为纯文本以便修改。
### 导出 PNG
点击工具栏中的 **Export PNG** 按钮，将当前思维导图保存为高清 PNG 图片（2 倍分辨率）。系统文件对话框允许你选择保存位置。
## 安装
### 通过 Obsidian 社区插件安装（推荐）
1. 打开 **设置 → 社区插件 → 浏览**
2. 搜索 **Light Mindmap**
3. 点击 **安装**，然后 **启用**
### 手动安装
1. 从 [最新版本](https://github.com/ninglg/obsidian-light-mindmap/releases/latest) 下载 `main.js`、`manifest.json` 和 `styles.css`
2. 将这三个文件复制到 `<vault>/.obsidian/plugins/obsidian-light-mindmap/` 目录下
3. 重新加载 Obsidian，在 **设置 → 社区插件** 中启用该插件
## Frontmatter 示例
```yaml
---
type: mindmap
mindmap-structure: hybrid
mindmap-layout: balanced
mindmap-theme: vibrant
mindmap-line: curve
mindmap-node: rounded
---
```
## 兼容性
- 最低 Obsidian 版本：**1.4.0**
- 支持桌面端和移动端
- 兼容 Obsidian 深色和浅色主题
## 许可证
MIT
Reference in a new issue View git blame Copy permalink