# md-mindmap

**Repository Path**: jueban21/md-mindmap

## Basic Information

- **Project Name**: md-mindmap
- **Description**: 在 VSCode 里同时看 Markdown 文档和脑图，**点脑图节点，文档预览滚到对应章节**；滚动编辑器时，脑图自动高亮当前章节。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown Mindmap Viewer

在 VSCode 里同时看 Markdown 文档和脑图，**点脑图节点，文档预览滚到对应章节**；滚动编辑器时，脑图自动高亮当前章节。

> 官方 Markdown 预览不开放脚本注入，所以市面上没有插件能做这件事 —— 本插件用 webview 自建双栏视图绕开这个限制。
>
> 脑图渲染基于开源项目 [markmap](https://markmap.js.org)（MIT），本项目与其无隶属关系。

**源码仓库**：<https://gitee.com/jueban21/md-mindmap> ｜ **问题反馈**：[Issues](https://gitee.com/jueban21/md-mindmap/issues) ｜ **安装包**：[发行版](https://gitee.com/jueban21/md-mindmap/releases)

## 文档导航

| 文档 | 内容 |
|---|---|
| [01 设计思路](docs/01-设计思路.md) | 需求从哪来、为什么现成方案都不行、方案怎么演进、四条体验原则 |
| [02 技术方案](docs/02-技术方案.md) | 架构图、消息协议、点击联动与行定位实现、构建策略、已知限制 |
| [03 安装教程](docs/03-安装教程.md) | 安装包安装 / 源码构建 / 调试模式 / 使用说明 / 故障排查 |
| [04 发布与合规](docs/04-发布与合规.md) | 发布到扩展市场的步骤、开源许可证合规、变现路径与预期 |
| [05 发布操作卡](docs/05-发布操作卡.md) | 三步发布的具体操作（创建 publisher → 改 ID 重打包 → 上传） |
| [第三方依赖声明](THIRD-PARTY-NOTICES.md) | 76 个依赖的许可证清单与全文（分发时须随包附带） |
| [安装包](https://gitee.com/jueban21/md-mindmap/releases) | 到「发行版」页下载 `md-mindmap-0.3.0.vsix`（274KB，离线可用）；本地构建产物在 `dist/` |

## 快速开始

```bash
# 安装（先到 Releases 页下载 vsix，或直接用本地 dist/ 里的文件）
code --install-extension md-mindmap-0.3.0.vsix
```

也可以从源码构建：

```bash
git clone https://gitee.com/jueban21/md-mindmap.git
cd md-mindmap && npm install && npm run build && npm run package
```

装完 **重载窗口**（`Ctrl+Shift+P` → `Reload Window`），打开任意 `.md`，按 **`Ctrl+Alt+M`**。

## 功能

| 功能 | 说明 |
|---|---|
| 双栏视图 | 文档预览 + markmap 脑图，**默认左右分屏**，中间分隔条可拖拽调比例，可切上下 |
| 同组标签页 | 按 `Ctrl+Alt+M` 时脑图作为**标签页**开在代码旁边，不拆新列；想要分屏就把 `mdMindmap.openToSide` 打开 |
| 单面板复用 | 右键打开另一个 md 时**不新开分屏**，复用同一个面板切换内容，层级/布局/比例保持不变 |
| 默认两层 | 脑图默认只展开两层，大文档不糊屏；工具栏可切 1/2/3/4 层或全部 |
| 预览 → 源码 | 悬停任意块（标题/段落/列表/代码/表格/引用）点右上角 `↗ 行号`，或 `Ctrl/⌘ + 点击`，编辑器定位到该行并聚焦 |
| 双向联动 | 点节点 → 预览跳章节；滚动编辑器**或滚动预览** → 脑图自动高亮当前章节节点（工具栏「联动」可关） |
| 看过的收起 | 滚动联动展开过的分支，路径移开后自动折叠；手动展开的分支不会被收走 |
| 位置可换 | 工具栏「交换」按钮一键对调预览与脑图的位置（左↔右 / 上↔下），比例保持、状态记忆 |
| 分屏可拖 | 中间分隔条拖拽调比例，比例记忆 |
| 定位可关 | 点节点默认只滚动预览、不动编辑器；需要时用工具栏 `定位源码` 或 `mdMindmap.jumpToSource` 开启 |
| 脑图 → 文档 | 点节点：预览滚动高亮 + 编辑器光标定位源码行 |
| 文档 → 编辑器 | 点预览标题：编辑器定位到对应行 |
| 实时同步 | 改 md（含外部程序改写）自动重绘双栏 |
| 图片正常 | 相对路径 / 远程 / base64 图片均可显示，坏链显示红色占位框 |
| 主题跟随 | 全部 `--vscode-*` 变量，明暗主题自适应 |
| 离线可用 | markmap / d3 / markdown-it 全打包，不依赖 CDN |

## 目录结构

```
md-mindmap/
├─ README.md              # 本文件（索引）
├─ docs/                  # 设计思路 / 技术方案 / 安装教程
├─ dist/                  # 安装包 vsix
├─ src/
│  ├─ extension.ts        # 入口：注册 mdMindmap.open
│  ├─ MindmapPanel.ts     # 面板生命周期、消息路由、文件监听、行定位
│  └─ webview/main.ts     # 前端：渲染 + 点击联动
├─ media/
│  ├─ webview.css         # 主题化样式
│  └─ bundle.js           # 构建产物（勿手改）
├─ out/                   # 主进程构建产物
├─ esbuild.js             # 双产物构建脚本
└─ package.json
```

## 开发命令

```bash
npm install        # 安装依赖
npm run build      # 构建
npm run watch      # 监听重建
npm run typecheck  # 类型检查
npm run package    # 打包 vsix
```

按 `F5` 启动扩展开发宿主，改完代码在宿主窗口 `Ctrl+R` 重载。

## 版本

| 项 | 值 |
|---|---|
| 插件版本 | 0.3.0 |
| 扩展 ID | `huxuan.md-mindmap` |
| 源码 | <https://gitee.com/jueban21/md-mindmap> |
| VSCode 引擎 | `^1.85.0` |
| markmap | 0.18.12 |
| markdown-it | 14.1.0 |

## 已知限制

- 节点与标题按**文字**匹配：同名标题只跳第一处，列表节点只能就近匹配上级标题
- 超大文档（数千节点）点「展开全部」会短暂卡顿
- 不支持未保存的 untitled 文档

详见 [技术方案 · 已知限制](docs/02-技术方案.md#七已知限制)。