Markdown 工具箱 feely0208/dsh-markdown-kit

@deepwhale-cn/dsh-markdown-kit

Listed on dsh-plugin.org

Markdown 工具箱：整目录的 .md 一次处理完 —— 转成 Word、生成目录、盘点链接、按文件名合并。
不打开编辑器、不动原文件，产物单独放在输出目录。

关键词：Markdown 转 Word · md 转 docx · 批量生成目录 · 提取链接 · 合并 Markdown · 技术文档交付 · 周报合并 · 文档链接盘点

不装会怎样

几十篇技术文档要交给不用 Markdown 的人：不装就只能一篇篇复制正文、手工套标题样式、把表格重画一遍、把代码块改成等宽字体 —— 一晚上出三篇，格式还前后不一。

要给一整本手册做目录：只能翻着文档一个个抄标题、手工拼锚点链接，正文一改标题目录就全错。

文档站要上线前想核对外链、想知道哪个链接写了三遍：只能肉眼翻，几百个链接翻完还是心里没底。

每周把组里几个人的周报合成一份：手工 copy 一遍、粘错顺序、漏掉一个人的情况一定有。

这些活都是「机械但量大、错一次很难发现」。这个插件把它们交给脚本：输入一个文件或一个目录，输出 Word / TOC.md / links.txt / merged.md，每件产物都能打开核对。

能做什么

dsh-markdown-kit <action> --input <文件或目录> [--out <目录>] [--json]

| 子命令 | 作用 | 产物（可核对） |
| to-docx | Markdown → Word：#/## 标题、段落、无序/有序列表、代码块（等宽字体 + 浅灰底纹）、引用、表格、链接文字 | 每篇一个 .docx；JSON 里给出标题/表格/代码块的条数 |
| toc | 按标题层级生成目录，锚点按 GitHub 规则（#第一章-总览，重名自动 -1） | TOC.md；目录模式带文件相对路径（01-指南.md#...），单文件模式是纯锚点 |
| links | 提取 文字、图片、裸 URL、<https://…> 自动链接 | links.txt（文件/行/类型/文字/URL 制表符分列）+ --json 汇总（按文件统计、重复项） |
| merge | 按文件名自然顺序（1、2、10 而不是 1、10、2）合并，每个文件前加 # 文件名.md 分隔标题 | 一个 merged.md |

共同约定：

- 不修改输入文件：只读 .md，所有产物写进输出目录；
- 默认输出 <输入目录>/_输出，可用 --out 指定；
- 同名文件不覆盖：已存在时自动变成 报告_1.docx、报告_2.docx；
- 目录递归处理，跳过 .git、node_modules、_输出 和所有点开头的目录；
- 只有 to-docx / --demo 需要 python-docx；toc / links / merge 只要 python3；
- --json 输出结构化结果（含每个文件的产物路径与条数），方便脚本和 CI 断言；
- 出错退出码非 0 并说明缺什么：2 参数/输入问题、3 缺依赖、1 运行失败。

整目录 Markdown 转 Word dsh-markdown-kit to-docx --input ./文档 --out ./word

给整本手册生成目录（带文件路径锚点） dsh-markdown-kit toc --input ./文档

单篇文档生成目录（纯锚点，可直接贴进正文） dsh-markdown-kit toc --input ./文档/README.md --out ./目录

盘点链接与重复项 dsh-markdown-kit links --input ./文档 --json

按文件名顺序合并周报 dsh-markdown-kit merge --input ./周报 --out ./合并

不能做什么

- ❌ 不是完整的 CommonMark 渲染器。内置解析器只覆盖「标题 / 段落 / 列表 / 代码块 / 引用 / 表格 / 内联链接」这七种块；HTML 块、脚注、数学公式、任务列表 - [ ]、Mermaid/图表、嵌套引用、参考式链接
（[文字][ref] + [ref]: url）都不支持 —— 它们会退化成普通段落文字，不会报错。
- ❌ 图片不会嵌进 Word：封面 只保留 封面 这段文字，不读图片、不调整大小。
需要图文混排的成品请用专业工具。
- ❌ 不保证排版等同于设计稿：标题字号/页边距是固定的一套（中文用微软雅黑、代码用 Consolas），不做页眉页脚、页码、分页、封面页、多栏；表格只保留文字和表头加粗，单元格合并/列宽/对齐会丢。
- ❌ 有序列表在 Word 里可能跨列表连续编号（List Number 样式共用一个编号序列），需要精确编号请自己写 1. 文字。
- ❌ to-docx 会跳过文档开头的 YAML front matter；toc 同样跳过。merge 原样保留每篇内容（含 front matter）。
- ❌ links 不扫描围栏代码块：代码里的 URL 不是文档链接（这条是刻意设计，避免误报）。
mailto:、tel:、相对路径都会照原样记录，但只有 http(s):// 会被当作「裸 URL」识别。
- ❌ 只处理 .md / .markdown（UTF-8）。其他后缀会直接报错退出；不做编码转换、不做 OCR、不导出 PDF。
- ❌ 不做增量/监听：每次都是全量重跑；重复跑会生成带 _1 的新文件而不是覆盖。
- ✅ 全部在本机处理，不联网、不上传文档、不调用任何第三方 Markdown 服务。

安装

dsh plugin --profile web add @deepwhale-cn/dsh-markdown-kit

运行依赖本机的 python3（插件不会替你装）；to-docx 还需要 python-docx。缺依赖时命令行会直接打印安装命令：

python3 -m pip install python-docx
macOS 没有 python3 时
brew install python3

用法

dsh-markdown-kit --help
dsh-markdown-kit --demo # 自造样例 Markdown 跑完整流程，打印产物路径 dsh-markdown-kit <action> --input <文件或目录> [--out <目录>] [--json]

--demo 会在系统临时目录里造两篇样例（含中文标题、列表、代码块、表格、链接），依次跑 to-docx / toc / links / merge，不碰你的任何文件；跑完按打印出来的路径打开产物，就知道它长什么样、能不能对上你的需求。

License

MIT © 温州深鲸智能科技有限公司