简体中文 · English

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 下载最新版的三个文件：main.js、manifest.json、styles.css。
2. 在 vault 里新建文件夹 <你的仓库>/.obsidian/plugins/markdown-toolkit/，文件夹名要和插件 id markdown-toolkit 完全一致。
3. 把三个文件放进去，重启 Obsidian，再到「设置 → 第三方插件」里启用 Markdown Toolkit。

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

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

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

---

设置

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

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

---

隐私与兼容性

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

---

开发

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 做自动排版。
• 图标和交互风格的思路来自 Obsidian 原生编辑器和 editing-toolbar。

许可

MIT © hellokunzai