简体中文 · [English](README.en.md)

# Markdown Toolkit

> 在笔记里可视化编辑图表、思维导图、流程图等 12 种图形，改完写回纯文本。同一套画布也能编辑带公式的 Markdown 表格。另有编辑器工具栏、文件浏览器增强和附件管理几块工具。

- 当前版本：0.21.0
- 最低支持 Obsidian：1.4.16
- 桌面端和移动端都能用。不联网，不要账号，没有内购。

---

## 为什么是纯文本

笔记里的图，常见做法是截图或导出成附件，代价是它们再也没法和正文一起改。这个插件换了个前提：图表和表格继续以纯文本存在笔记里，编辑器只是给这份文本配的一层可视化操作界面。

于是有三件事自然成立：

- 数据待在围栏代码块或普通 Markdown 表格里，能进 Git，能跨平台搬走，任何 Markdown 工具也读得懂。
- 编辑器改的就是这份文本，不存在第二份副本，也没有需要导出的中间格式。
- 渲染和排版全在本地完成，不请求外部服务。

下面五块能力都能在设置的「功能模块」页签单独开关。

---

## 它能做什么

### 1. 图形可视化编辑器

在笔记里用代码块写图表，点一下代码块就打开画布式编辑器。拖动排版后，结果写回代码块源码。内置 12 种图形：

| 图形 | 首行关键字 | 适合 |
|---|---|---|
| 思维导图 | `mindmap` | 知识梳理、头脑风暴 |
| 流程图 | `flowchart TD` | 业务流程、分支逻辑 |
| 时序图 | `sequenceDiagram` | 接口调用、服务交互 |
| 类图 | `classDiagram` | 面向对象设计 |
| 状态图 | `stateDiagram-v2` | 状态流转 |
| 实体关系图 | `erDiagram` | 数据库表关系 |
| 甘特图 | `gantt` | 项目排期 |
| 饼图 | `pie` | 占比 |
| Git 图 | `gitGraph` | 分支历史 |
| 时间线 | `timeline` | 事件先后 |
| 鱼骨图 | `ishikawa-beta` | 根因分析 |
| 柱状图 | `xychart-beta` | 分类数值对比 |

- 自研 SVG 渲染，配 dagre 做自动布局。不依赖外部 CDN，也不用联网。
- 画布上可以拖节点、改名字、加子节点和兄弟节点、删除节点。位置会记进代码块里的一行注释，下次打开还是你摆好的样子，别的渲染器读到这行会直接跳过。
- 自带整理布局、撤销重做、缩放和五种节点形状（矩形、圆角、圆形、菱形、六边形）。
- 代码块右上角有编辑入口，也能导出 SVG 或 PNG，或者开全屏预览看大图。
- 渲染失败时不会整块变空白，而是把源码显示出来并说明是哪一种图形出的问题。
- 设置里的图表清单可以按名称搜索，12 种都在一处，每种都标了关键词、典型场景和是否支持可视化编辑。
- 移动端可以双指捏合缩放。

相关命令：`插入思维导图代码块`、`插入流程图代码块`、`插入图表…`、`把选中的大纲转成思维导图`、`编辑光标处的图形`。

### 2. 表格编辑器

阅读视图和实时预览里，插件会接管 Markdown 表格，给每张表套上画框：

- 有公式和没公式的表都会被框住。唯一的例外是实时预览里光标所在的那张表，那正是你在打字的表，交回 Obsidian 原样渲染。
- 在格子里写公式（比如 `=sum(B2:B4)`）就会算出结果。格子里显示值，源码里留公式。算出来的格子带 `ƒ` 标记和底色，不想要可以在「表格编辑器」页签关掉。
- 公式有 `sum`、`avg`、`count`、`max`、`min`，支持 `B2:B4` 这样的区域引用，也支持 `+ - * /` 和括号的算式，比如 `=B2-C2`。写错了显示成 `#REF!` 这类值，不会把整张表渲染崩掉。
- 画框角上有按钮和公式计数徽标，可以把表格导出成 CSV 或 Markdown，也可以打开可视化编辑器。
- 编辑器是电子表格式的：字母列标加数字行号，滚动时吸顶；拖拽或 Shift 选范围，方向键和 Tab 移动，双击格子输入，拖填充柄续填序列，Del 清空，Ctrl+C/V 搬移；在边缘外的空白格里一编辑就自动扩表。列宽行高能拖，但只对这次编辑有效，不写回笔记。列标和行号右键可以整列整行插删。公式栏显示选中格的原始公式，格子里显示算出来的值。名称框能直接跳到某个格子。
- 移动端可以双指捏合缩放。
- 表格的自动保存和保存间隔是独立设置的，跟图表编辑器分开。

工具栏里还有插入表格按钮，以及表格和列表互转两个文本工具。

### 3. 编辑器工具栏

一条可自定义的格式化工具栏，默认 40 多个按钮，子菜单能拖动排序：

- 格式刷：把一段文字的格式套到另一段。
- 下划线：Markdown 本身没有下划线语法，这个按钮写的是 Obsidian 能渲染的 HTML 标签。
- 文本批处理：15 个工具，去空行、合并或拆分行、去重、加前后缀、加行号、去首尾空格、折叠空白、去掉全部空白、表格和列表互转、按规则提取，分在「行操作 / 文本处理 / 高级工具」三组里。
- 对齐：左对齐、居中、右对齐、两端对齐。走内联样式，纯文本照样读得懂。
- 双色板：字体颜色和背景颜色各有一支取色面板，面板里还能用吸管取屏幕上的颜色。
- 全屏专注模式：编辑区铺满屏幕，侧栏和状态栏都收起来。
- 图表子菜单：工具栏上自带「图表」入口，可以直接插流程图或思维导图代码块，也能打开选择器挑任意一种。
- 分组标题：能在工具栏里插自己的分段标题，文字可改可删，按钮按你的习惯分区。
- 移动端工具栏：手机上会自动隐藏 Obsidian 自带的那条键盘上方工具条，只留插件这一条。装上就生效，不用设置。
- 工具栏底色：整条工具栏自己的底色。可以跟主题、可以透明，也能从八个预设里挑一个，或者直接填 `#rrggbb`、`rgb()`、`hsl()`、`var(--主题变量)`。

相关命令：`切换格式刷`、`下划线`、`字体颜色`、`背景颜色`、`全屏专注模式`。

### 4. 文件浏览器增强（默认关闭）

> 这个模块默认关，在「功能模块」页签打开后才生效。

- 隐藏规则：按精确名称、`startsWith::` 前缀或 `endsWith::` 后缀隐藏文件浏览器里的条目，比如隐藏 `attachments` 文件夹或 `.obsidian` 这类条目。可以忽略大小写，也可以顺手把命中的条目加进 Obsidian 的「已排除文件」，让它们从搜索、关系图谱和反链里消失。状态栏会显示当前隐藏了多少条。
- 手动排序：给文件夹定自定义顺序，随时能改回字母序。设置里能逐条展开查看已排好的下级顺序，并拖动行内把手调整。

### 5. 附件管理（默认关闭）

> 这个模块默认关，在「功能模块」页签打开后才生效。

- 附件文件夹模板：用变量决定附件落在哪，可以相对当前笔记，也可以相对仓库根。变量有 `${noteFileName}`、`${folderPath}`、`${originalFileName}` 和 `${date:YYYYMMDDHHmmss}`。
- 文件名模板：保存和重命名附件时套用。
- 特殊字符处理：把文件名和文件夹名里的特殊字符替换或删掉，少踩同步和跨平台的坑。
- 同步重命名 / 移动：重命名或移动笔记时，附件文件夹跟着改名或搬走，所有链接自动更新。
- 重名分隔符：粘贴同名文件时自动加分隔符和计数器，直到找到空闲名。
- 空文件夹策略：笔记搬走后，空的附件文件夹可以保留、删除，或者连同空的上级目录一起删。
- 孤立附件清理：删除笔记时，把它带出来的孤儿附件送进回收站，还能恢复。

---

## 命令

插件的命令都能在命令面板里搜到，也能绑快捷键，大部分还能加到工具栏上。

| 命令 | 说明 |
|---|---|
| 插入思维导图代码块 | 插入一个 `mindmap` 代码块 |
| 插入流程图代码块 | 插入一个 `flowchart` 代码块 |
| 插入图表… | 从 12 种里挑一种插入 |
| 把选中的大纲转成思维导图 | 选中多级列表或标题，生成思维导图 |
| 编辑光标处的图形 | 光标在代码块内时打开可视化编辑器 |
| 切换格式刷 | 开关格式刷 |
| 下划线 | 开关下划线 |
| 字体颜色 | 打开取色面板 |
| 背景颜色 | 打开取色面板 |
| 全屏专注模式 | 切换全屏专注模式 |
| 文本工具（15 个） | 去格式取纯文本、全角转半角、插入空行、去空行、拆成句、合并行、去重、加前后缀、加行号、逐行去空格、折叠空白、去掉全部空白、列表转表格、表格转列表、按规则提取 |
| 文本对齐（4 个） | 左对齐、居中、右对齐、两端对齐 |

---

## 安装

插件已上架 Obsidian 社区插件市场，在 Obsidian 的「设置 → 第三方插件」里搜就能装。也可以走下面两种方式。

### 方式一：手动安装

1. 到 [Releases](https://github.com/hellokunzai/obsidian-markdown-toolkit/releases) 下载最新版的三个文件：`main.js`、`manifest.json`、`styles.css`。
2. 在 vault 里新建文件夹 `<你的仓库>/.obsidian/plugins/markdown-toolkit/`，文件夹名要和插件 id `markdown-toolkit` 完全一致。
3. 把三个文件放进去，重启 Obsidian，再到「设置 → 第三方插件」里启用 Markdown Toolkit。

> 注意：插件 id 和文件夹名必须同名，否则配置读不出来，也存不进去。

### 方式二：通过 BRAT 安装（Beta）

1. 先装 [BRAT](https://github.com/TfTHacker/obsidian42-brat) 插件。
2. 在 BRAT 里选「Add a beta plugin」，填仓库地址 `hellokunzai/obsidian-markdown-toolkit`。
3. 启用后就能在第三方插件列表里看到它，以后的更新也交给 BRAT。

---

## 设置

一共七个页签。最左边的「功能模块」固定在第一位，始终可见；其余页签跟着对应模块的开关走，关掉哪个模块，它的页签就一起消失。

| 页签 | 内容 |
|---|---|
| 功能模块 | 每个模块一个总开关：工具栏 / 表格 / 图表 / 附件处理 / 文件隐藏 / 文件排序。关掉某模块会同时隐藏它的设置页签、停用编辑器里的对应功能。默认开工具栏、表格、图表；附件处理、文件隐藏、文件排序默认关 |
| 编辑器工具栏 | 工具栏底色（跟随主题 / 透明 / 八个预设 / 自定义色值）、命令搜索、增删命令与子菜单、分组标题、拖拽排序 |
| 表格编辑器 | 表格自动保存与保存间隔、公式高亮（阅读视图 / 编辑器 / 预览里的 ƒ 标记与底色）、公式速查表 |
| 图表编辑器 | 自动保存与保存间隔、图表类型清单（可按名称搜索，含关键词、典型场景与可视化编辑支持列） |
| 附件处理 | 附件文件夹与文件名模板、特殊字符处理、同步重命名/移动、重名分隔符、空文件夹策略、孤立附件清理 |
| 文件隐藏 | 要隐藏的条目、忽略大小写、启用隐藏、加入已排除文件列表、状态栏指示、侧边栏的眼睛按钮 |
| 文件排序 | 显示排序按钮、逐条展开查看已排好的下级顺序并拖动行内把手调整顺序、按路径搜索、单条或全部清除自定义顺序 |

---

## 隐私与兼容性

- 不发起任何网络请求，所有计算都在本地完成。
- 不需要外部账号，也没有付费功能。
- 桌面端和移动端都能用（`isDesktopOnly: false`），最低支持 Obsidian 1.4.16。
- 界面文案跟随 Obsidian 的语言设置，内置英文和简体中文两套。

---

## 开发

```bash
npm install
npm run dev      # 监听改动，输出 main.js
npm run build    # 类型检查 + 生产构建
```

构建产物是 `main.js`、`manifest.json` 和 `styles.css` 三个文件，源码在 `src/` 下按 `core`（纯逻辑）、`charts`、`editor`、`embed`、`features`、`ui`、`utils` 分了目录。发版时给提交打一个 `0.21.0` 形式的 tag（跟 manifest 的版本号一致，不带 `v` 前缀）推上去，GitHub Actions 会构建并创建 Release。

---

## 鸣谢

- 图形布局用 [dagre](https://github.com/dagrejs/dagre) 做自动排版。
- 图标和交互风格的思路来自 Obsidian 原生编辑器和 [editing-toolbar](https://github.com/cumany/obsidian-editing-toolbar)。

## 许可

MIT © hellokunzai