@deepwhale-cn/dsh-markdown-kit

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：![封面](cover.png) 只保留 封面 这段文字，不读图片、不调整大小。 需要图文混排的成品请用专业工具。
• ❌ 不保证排版等同于设计稿：标题字号/页边距是固定的一套（中文用微软雅黑、代码用 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。缺依赖时 CLI 会直接打印安装命令：

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 © 温州深鲸智能科技有限公司