手上有几十份 Word 文档要进文档库标题是手动加粗的表格是拖出来的图片全是浮动在文字上方的公式清一色截图。你把这样一份文件丢给任何转换工具出来的 Markdown 都是一场灾难——满屏乱码似的星号图片全部丢失公式变成空白。Word 转 Markdown 这件事工具只占三成剩下七成全在文档本身的规范性上。这篇教程面向所有需要把 Word 往 Markdown 搬的人写技术文档的、维护知识库的、做内容迁移的甚至只是想把毕业论文塞进个人笔记系统的。我会把选型、预处理、命令参数、批量脚本、收尾清洗、报错排查整条链路摊开讲每一步都说明白为什么这么做哪些坑我踩过哪些参数实测下来最稳。1. 先搞清楚Word 和 Markdown 到底差在哪1.1 一个是排版成品一个是结构草稿很多人转换失败根子在于没意识到这两种格式的世界观完全不同。Word 文档里这段字看起来像标题靠的是字体、字号、加粗、居中的组合它是视觉描述Markdown 里## 二级标题是一个语义标记它告诉渲染器这是一个二级标题至于显示成多大、什么颜色交给渲染器决定。这个差异直接决定了转换质量。Word 里你手动把一行字调成 18 号加粗居中转换工具看到的是一个字号 18、加粗、居中、没有样式名的普通段落它没有任何依据判断这是一级标题只能原样输出成一个普通段落。反过来如果你在 Word 里把那一行套上标题 1样式Pandoc 这类工具就能准确把它变成#。生活化的类比Word 像一份手绘海报所有效果都用笔直接画上去Markdown 像一张施工图纸图纸只写这里是一扇门至于门是木头的还是玻璃的装修时再说。你要做的是把海报还原成图纸而不是把海报扫描一遍。顺着这个逻辑,转换前要做的第一件事不是选工具,而是把 Word 文档里的视觉效果翻译回语义样式。这件事我后面第 4 章会专门展开先记住结论样式规范程度决定转换质量上限工具只决定下限。1.2 哪些文档值得转哪些转了就是自找麻烦不是所有 Word 都适合转 Markdown。我按文档类型分了个类你可以对号入座。文档类型是否建议转换主要原因技术文档、接口说明强烈建议结构规整多为标题加段落加代码转换后可直接进 Git会议纪要、学习笔记建议内容以纯文本为主转换成本低论文、调研报告有条件建议公式、图表、参考文献多需要额外清洗宣传册、画册不建议双栏、文本框、艺术字Markdown 表达不了合同、公文不建议版式有法律意义字号行距都是要求Markdown 无版式带大量复杂表格的报表谨慎Markdown 表格不支持合并单元格和列宽判断标准很简单这份文档的价值在于内容结构还是在于版面呈现前者转后者别折腾。我见过有人把一份带花纹边框的荣誉证书转成 Markdown转完开始抱怨格式全丢了——它本来就不该转。还有一种情况值得单独说文档本身写得乱七八糟段落层级全靠回车硬凑图片和文字挤在一起。这种文档转 Markdown 之前得先花时间做内容整理别指望工具能帮你把逻辑理清楚。工具的职责是搬运不是编辑。1.3 动手前的文档体检清单正式开干之前我会做一遍快速体检五分钟就能过完。这一步省下来后面可能要多花两小时修。看扩展名.doc是老的二进制格式.docx是新的 XML 格式。转换工具对.docx的支持远好于.doc遇到.doc先在 Word 里另存为.docx。看有没有宏.docm结尾的文档带宏。转换前另存为.docx既避免转换工具误触宏也减少内容干扰。顺带说一句来源不明的文档不要随手启用宏宏安全这道线不能松。看文档体积几十兆的文档转换起来又慢又容易崩。如果文档里塞了大量高分辨率图片可以先用 Word 的压缩图片功能瘦身再转换。顺带一提Word 关闭时卡顿很多时候就是这种大文档在后台保存或重排导致的转换前先另存一份干净副本反而更省事。看修订和批注右键看有没有接受所有修订没处理。修订状态下的内容转换结果会很混乱批注则可能被一并转成正文。看域代码和目录自动生成的目录是域转换后可能变成一堆无意义的文字或空行建议先把目录域转成纯文本或者直接删掉Markdown 侧再重新生成。看公式文档里如果有公式先确认是 Word 自带公式还是 MathType 之类的第三方对象这两条路的处理方式完全不同。体检做完你基本能预判这份文档转出来会有几成能用。2. 转换方案怎么选四条路线摆在台面上比2.1 纯手工路线适合文件少、要求高的场景手工不等于低效。当文档只有一两份且对结果要求极高时我会直接打开 Word 复制正文粘到编辑器里然后手动加标记。听起来笨但有几件事是工具做不到的调整逻辑顺序、合并重复段落、把口语化表达改写成书面语。手工路线的正确姿势不是一句一句抄而是先粗后细先把全文粘过去用编辑器的批量替换把明显的空行、全角标点、多余空格清掉再补标题和列表。我通常的节奏是一份 3000 字的文档手工整理 20 分钟左右质量比转换再修要稳。编辑器里熟悉几个正则替换效率会高一大截。这条路线的缺点是没法规模化。你有 50 份文档手工就是在给自己上刑。所以判断标准是文档数量小于 3 且结构混乱手工数量多或结构规整走工具。2.2 Pandoc 命令行批量场景的最优解Pandoc 是文档格式转换里绕不开的一个工具它的定位就是文档界的翻译器输入输出格式覆盖极其广。Word 转 Markdown 这条链路上它的优势很明确支持从.docx直接读取样式信息标题层级、列表、加粗斜体都能正确映射能把内嵌图片导出成独立文件并自动写好 Markdown 图片路径能把 Word 自带的数学公式OMML 格式转成 LaTeX 数学表达式命令行调用配合 shell 脚本或者 Python 就是批量流水线。缺点也说清楚它对样式依赖度极高文档里手动加粗的假标题它一样识别不出来MathType 那种嵌入式对象它也读不到版本不同参数行为略有差异跨机器复现时要注意版本号。另外提一句Pandoc 不是唯一选择。市面上有一些开源的任意格式转 Markdown项目本质上是给 Pandoc 或者类似的解析库套了一层界面功能大同小异。与其装一堆不如把 Pandoc 一条命令吃透。2.3 图形化工具与在线服务门槛低但要留意边界不想碰命令行的有几类图形方案可选。桌面端有一些带界面的转换器拖文件进去点按钮就出结果编辑器生态里也有不少插件集成了转换能力。它们上手快适合偶尔用一次的人。在线转换服务我要多说两句。把内部文档上传到别人的服务器这件事本身就值得掂量。技术文档、合同、商业计划这类内容我建议一律走本地工具真要是在线转先确认文档里没有敏感信息转完及时清掉服务端缓存如果它提供这个选项。图形化工具还有一个隐性成本出问题时你不知道中间发生了什么。Pandoc 报错你能看到具体是哪一行、哪个参数图形工具只会弹一句转换失败剩下的全靠猜。所以我的一般建议是只要这件事你会做第二次就值得花半小时把命令行学会。2.4 编辑器与插件内置能力顺手但不万能现在主流的 Markdown 编辑器不少都支持直接粘贴 Word 内容并自动保留基本结构。这条路线的优点是零切换成本你在编辑文档的地方就把转换做完了。但它有两个天花板。一是映射规则相对简单遇到嵌套列表、复杂表格、脚注这些结构处理得比较粗糙二是批量和自动化能力弱你没法写个脚本让它把 200 份文档过一遍。我的实际做法是混着来单份文档用编辑器粘贴后手工修批量文档走 Pandoc两者互补而不是二选一。3. Pandoc 从零上手安装、第一条命令、参数拆解3.1 安装与环境自检安装方式按系统区分各平台都有成熟的包管理渠道# macOS brew install pandoc # Windows用自带包管理器 winget install --id JohnMacFarlane.Pandoc # 类 Unix 环境 sudo apt install pandoc装完先验证版本这一步很重要因为后面有些参数是较新版本才有的pandoc --version输出里会显示版本号和它支持的输入输出格式列表确认里面有docx就行了。如果你还需要把 Markdown 导出成 PDF那要额外装一个排版引擎LaTeX 发行版或者别的这个后面第 7 章会讲。提示装完之后把 Pandoc 加入系统 PATH否则在脚本里调用会提示找不到命令。Windows 下用 winget 装一般会自动配好绿色版手动解压的要自己加。3.2 最小可用命令拆开看先别急着背参数。从最简的一条命令开始pandoc input.docx -o output.md这条命令能跑通说明环境没问题。Pandoc 会根据文件扩展名自动推断输入输出格式.docx走 Word 解析器.md走 Markdown 写出器。默认写出的是 Pandoc 自己的 Markdown 方言功能全但通用性一般。接着换成更通用的方言pandoc input.docx -f docx -t gfm -o output.md这里-f指定输入格式-t指定输出格式。gfm是 GitHub Flavored Markdown也就是 GitHub、多数笔记软件、多数静态站点生成器都认的那套方言管脚注、表格、任务列表、删除线。日常转换我基本都用它。如果你的目标平台是别的方言比如某些国产编辑器也可以试试-t markdown_strict它更保守只输出最基础的语法。3.3 三个最该记住的参数参数不用背全但这三个必须会因为它们直接决定转换结果能不能用。第一个是--wrapnone。不加这个参数Pandoc 默认会在 72 个字符左右硬折行一段长文字会被切成好几行中间插入真实换行符。在 Markdown 里这意味着什么在 GFM 里单个换行不产生换行效果但会破坏 diff 的可读性更重要的是如果你后面用别的工具处理这个文件行结构是乱的。加上它一个段落就是一行。pandoc input.docx -t gfm --wrapnone -o output.md第二个是--extract-media./assets。Word 里的图片是打包在 docx 里的不导出的话 Markdown 里引用不到。这个参数会把这些图片抽出来放到指定目录pandoc input.docx -t gfm --wrapnone --extract-media./assets -o output.md生成的文件里会出现类似的图片引用。注意这个路径是相对输出文件的位置算的所以你的输出文件和 assets 目录要保持相对位置关系别转完就把目录挪走。第三个是--markdown-headingsatx。不加这个Pandoc 可能把标题写成下划线式正文下面跟一排很多渲染器不认。指定 atx 之后标题统一输出成#开头通用性最好。pandoc input.docx -t gfm --wrapnone --markdown-headingsatx \ --extract-media./assets -o output.md这三个参数组合起来是我日常使用频率最高的一条命令。3.4 批量转换脚本与目录约定单文件搞定之后就得考虑批量。这里我建议先把目录结构定死不要边转边乱放project/ ├── word/ # 原始 Word 文档 ├── md/ # 转换后的 Markdown │ ── assets/ # 提取出来的图片 └── script.sh # 转换脚本目录约定好之后脚本就很好写#!/usr/bin/env bash set -euo pipefail SRC./word OUT./md mkdir -p $OUT find $SRC -maxdepth 1 -type f -name *.docx | while read -r file; do base$(basename $file .docx) pandoc $file \ -f docx \ -t gfm \ --wrapnone \ --markdown-headingsatx \ --extract-media$OUT/assets/$base \ -o $OUT/$base.md echo 已转换: $base done几个设计上的取舍说一下。set -euo pipefail是让脚本遇到错误立刻停下别默默跳过某个文件导致你以为全转完了其实漏了。每个文档的图片单独放到以文件名命名的子目录是因为多份文档里的图片经常重名都是image1.png混在一起会互相覆盖。find用-maxdepth 1只处理当前层避免把临时文件和子目录里的东西也扫进来。如果你更习惯 Python用 pypandoc 包一层也行import pathlib import pypandoc src pathlib.Path(./word) out pathlib.Path(./md) out.mkdir(exist_okTrue) for docx in src.glob(*.docx): target out / f{docx.stem}.md pypandoc.convert_file( str(docx), togfm, outputfilestr(target), extra_args[ --wrapnone, --markdown-headingsatx, f--extract-media{out / assets / docx.stem}, ], ) print(f已转换: {docx.stem})Python 版本的好处是后续好接内容处理逻辑比如转完自动做一遍正则清洗这是 shell 脚本写起来比较别扭的部分。4. Word 侧预处理九成的转换翻车都发生在这里4.1 样式规范化标题必须用样式不能靠手动加粗这是全文最重要的一条。转换工具判断标题层级靠的是 Word 的段落样式不是视觉效果。我见过最典型的错误是文档里所有标题都是选中文字点加粗把字号调到 16。转出来之后所有标题都成了普通段落全文挤成一坨。这时候你只能在 Markdown 里一行行加#文档一长就是苦力活。正确做法是在 Word 里用样式面板。标题 1 对应#标题 2 对应##以此类推。改完之后外观可能跟你原来的排版不一样但没关系Markdown 侧的外观由渲染器决定样式只需要携带层级信息。如果文档已经写完了几百个标题要手工改可以用一段宏批量处理。思路是找出加粗且字号大于等于 16的段落套上标题 1 样式。Sub BoldParagraphToHeading() Dim p As Paragraph For Each p In ActiveDocument.Paragraphs With p.Range.Font 注意混合格式时 Bold 会返回 wdUndefined必须排除 If .Bold True And .Size 16 Then p.Style ActiveDocument.Styles(标题 1) End If End With Next p End Sub这里有个很多人踩过的坑当一个段落里只有部分文字加粗时Range.Font.Bold返回的不是 True 也不是 False而是一个特殊值wdUndefined数值 9999999。如果你只判断If .Bold Then在某些情况下会把整段普通文字误判成标题。所以严格写法应该是先排除这个值。另外宏安全这件事必须重视。上面的代码是我自己写的、你能看懂逻辑的可以运行从网上随手下载的宏文件启用前一定要看清楚它做了什么。不确定的宏宁可不跑。4.2 图片先统一成嵌入型Word 里图片的环绕方式有好几种嵌入型、四周型、紧密型、衬于文字下方等等。Pandoc 对嵌入型图片处理得最好其他环绕方式的图片有的会丢失有的位置会跑到段落末尾去。批量处理的办法在 Word 里全选CtrlA然后依次点击图片格式里的环绕文字改成嵌入型。如果文档里图片很多也可以用宏把InlineShapes之外的图片统一转换一下。改完之后图片会变成占一行的字符看起来排得没那么花哨但对转换来说是最稳的状态。还有个细节图片的替代文本Alt Text会被 Pandoc 转成 Markdown 的图片描述。如果原文档里图片都带着有意义的替代文本转出来的 Markdown 可读性会好很多也利于无障碍阅读。有空的话顺手补一下这是加分项。4.3 公式MathType 对象是重灾区这个必须单独讲因为它是 Word 转 Markdown 里最容易翻车的地方。Word 文档里的公式有两种来源。一种是Word 自带公式编辑器写出来的底层是 OMML 格式Pandoc 能识别转换后会输出成 LaTeX 数学表达式比如$E mc^2$。这条路是通的。另一种是用第三方公式工具比如 MathType插入的在文档里是一个OLE 嵌入对象Pandoc 读它就是一个不认识的嵌入物结果通常是变成空白或者一张图片。这就是为什么很多人转完之后发现公式全没了。解决办法是转换之前在公式工具里把公式批量转成 Office 内置公式。多数第三方公式工具都提供了这个转换功能一般在转换公式之类的菜单里选择目标格式为 Office 内置公式格式OMML然后对全文执行一次。转完之后再走 Pandoc公式就能正常输出了。如果文档里的公式压根就是截图贴上去的那就没有任何工具能自动识别语义。这时候有两条路手工重新录入或者借助公式识别工具把图片转成公式文本再粘贴回去。前者慢但准后者快但需要逐条校对尤其是分式、上下标、希腊字母容易识别错。我的经验是公式数量少于 20 个就手工录超过 50 个再用识别工具加校对中间量看心情。还有个容易被忽略的点公式的字体。转成 Markdown 之后公式的显示字体由渲染引擎决定通常是数学专用字体跟你在 Word 里设的字体没关系。如果原文档要求公式必须用某个特定字体显示Markdown 这条链路是满足不了的得考虑保留 Word 版本。4.4 表格与列宽的那些坑Markdown 表格的能力边界很明确不支持合并单元格、不支持单元格内换行、不支持列宽。先说列宽。Markdown 表格的列宽由渲染器根据内容自动计算你在 Word 里费了半天劲拖出来的那套列宽转完一定会变。这是格式本身的能力问题不是工具不行。如果你确实需要控制列宽只有一条路在 Markdown 里直接写 HTML 表格用width属性控制但这会让文档不再纯 Markdown。顺便说一个高频问题Word 里表格列宽拖不动。这通常是三种原因之一。一是表格处于根据内容自动调整模式你没切换到固定列宽此时列宽由内容决定拖动会被系统改回去。二是表格属性里勾了指定宽度但单位或者数值设置有冲突。三是当前处于 Web 版式视图某些表格行为跟页面视图不一致。解决办法是选中表格在表格属性里关掉自动调整、选固定列宽再切回页面视图拖动。还有一个连带场景如果你是用程序批量生成 Word比如 Java 的 POI 或者 poi-tl 模板引擎生成的表格列宽不对或者打开后列宽自动变化本质原因是只设置了单元格宽度没有同时设置表格网格定义。POI 里要在tblGrid里声明列宽并给每个tc设置tcW两者一致Word 和 WPS 打开时才不会重新计算。这个是生成侧的问题跟转换侧正好是一对镜像一起了解有助于你理解列宽到底是怎么被描述的。那 Word 里复杂表格怎么办我的建议是分级处理简单的规整表格直接转Markdown 的管道表格足够用带合并单元格的表格先拆平把合并的信息用重复内容或者加一列标注来表达转完再决定要不要恢复结构实在复杂的导出成图片插入虽然丢了可编辑性但至少版式是对的。4.5 批注、修订、域代码和宏最后是三个隐形干扰项。批注在转换时可能被一并输出混在正文里非常影响阅读。转换前建议审阅一遍该处理的处理掉。修订如果没接受文档里同时存在原文和修改痕迹转换结果会是两份内容叠加这个必须先接受所有修订。域代码包括自动目录、交叉引用、页码字段这些。它们本质上是会变的内容转换工具往往处理不好。我的做法是把自动目录删掉Markdown 侧用工具重新生成多数编辑器和静态站点生成器都支持根据标题自动生成目录这样比转过来的死目录更实用。至于宏前面提过了转换前另存为不带宏的格式。这不只是为了转换顺利也是基本的安全习惯。5. 转换之后的收尾把半成品修成能用的文档5.1 换行、空行与软换行刚转出来的 Markdown 通常有几类问题多余的空行、意外的软换行、段落之间缺少空白行。先说 Markdown 的换行规则这个是基础但经常被搞混。在 GFM 里单个换行符不产生换行效果也就是你写完一行敲个回车接着写渲染出来还是同一段。想要强制换行有两种写法行尾加两个空格再换行或者直接用br标签。而段落之间必须有一个空行否则两段会被合并成一段。批量清理的时候我一般会用编辑器或者脚本处理几件事把连续三个以上的空行压成一个把行尾多余的空白字符删掉确认每个标题前后都有空行。这几步做完文件整洁度会明显提升。注意行尾的两个空格在很多编辑器里是不可见的容易被自动格式化工具清掉。如果你需要强制换行又不想依赖看不见的空格直接用br更稳妥。5.2 图片路径与资源目录图片路径是转换后最容易出问题的一环。--extract-media导出的路径默认是相对路径形式类似./assets/image1.png。这个写法在本地编辑器和 GitHub 上都能正常显示前提是图片确实在那个位置。常见的翻车场景有三种。一是你把 Markdown 文件挪到了别的目录相对路径就断了。二是把文档传到别的平台时只传了.md没传图片目录。三是多个文档的图片混在一个目录里出现重名覆盖。对应的处理办法保持一个文档配一个图片子目录的结构移动文件时连带目录一起移上传前用编辑器的链接检查功能扫一遍失效引用。如果用静态站点生成器通常有固定的资源目录约定比如放在static或者public下按它的规则来别硬扛。5.3 表格降级与列宽的现实前面说过列宽的问题这里补充一个操作层面的选择。Pandoc 输出gfm时简单表格会变成管道表格| 参数 | 说明 | | --- | --- | | -f | 指定输入格式 | | -t | 指定输出格式 |这种表格通用性最好但单元格里不能换行、不能有竖线有的话要转义成\|。如果表格比较复杂Pandoc 可能会自动降级成 HTML 表格也就是table标签。这不算错多数渲染器都支持只是文档不再是纯 Markdown 语法了。如果你更在意表格的可读性而不是通用性可以试试 Pandoc 的原生 Markdown 输出-t markdown它支持网格表格单元格里可以换行、可以有对齐信息源文件里看起来像一张真正的表。代价是支持的平台少一些有些编辑器不认。我的一般策略是要进 Git 仓库、要给别人看用 gfm自己本地维护、表格复杂用原生 markdown。5.4 数学公式清洗与显示公式转出来之后还有一道能不能显示的关。Pandoc 把 Word 公式转成 LaTeX 表达式输出成$...$或者$$...$$包裹的形式。问题是$并不是 GFM 标准里的数学标记它是很多编辑器自己扩展支持的。也就是说在 GitHub 上直接看公式可能不渲染显示成原始文本换到支持数学渲染的编辑器里就正常了。解决办法有两个。一是确认你的目标渲染环境支持$数学语法多数现代编辑器都支持可能需要手动开启开关。二是改用\( ... \)和\[ ... \]这种更通用的定界符通过 Pandoc 的参数或者转换后替换来调整。如果发布到网页上页面里要引入 MathJax 或者 KaTeX 这类渲染库公式才会真正显示出来。另外转出来的公式偶尔会带一些冗余的样式标记比如多余的空格、不必要的\displaystyle。数量少就手工清理数量多写个简单的正则替换批量过一遍。别指望百分百完美公式这块永远是能用就行、关键处人工确认。5.5 元数据与 front matter如果这份 Markdown 是要进静态站点或者知识库系统的通常还需要一段元数据头也就是 front matter--- title: 项目接口说明 author: 张三 date: 2025-01-15 tags: - 接口 - 文档 ---YAML 格式的三横线包裹放在文件最前面。这部分 Pandoc 不会自动生成除非你用了-s参数并配合元数据文件一般是我在收尾阶段统一补。批量补的话写个小脚本读一下原 Word 的文件名或者文档属性拼出对应的 front matter 插到开头比手工加省事得多。6. 问题排查速查那些让人抓狂的报错和怪现象6.1 转换报错与编码问题现象可能原因处理办法提示找不到文件或格式不支持文件是.doc老格式用 Word 另存为.docx再转输出中文变乱码环境编码不是 UTF-8确认终端和文件编码脚本里显式指定 UTF-8提示某字符无法编码文档里有特殊符号输出时指定编码参数或先替换掉异常字符命令跑通但输出是空的输入格式推断错误显式加-f docx指定输入格式参数报错说不认识Pandoc 版本太旧升级到较新版本或改用兼容参数编码问题在 Windows 环境里尤其常见。我的习惯是脚本里尽量显式写清楚编码不要依赖系统默认值省得换台机器就出问题。还有一类错误是文档本身损坏导致的。Word 提示在试图打开文件时遇到错误这种文件转换工具基本也读不了。处理方式是先在 Word 里用打开并修复功能试着救一下能打开之后另存为新文件再走转换流程。文件本身完好的前提下工具出错的概率其实很低。6.2 内容丢失类问题内容丢失比报错更让人头疼因为它是静默发生的。图片全丢八成是因为图片是浮动环绕方式。回到 4.2 节统一改成嵌入型。公式全丢MathType 这类 OLE 对象。回到 4.3 节先转成 Office 内置公式格式。表格内容缺失可能是嵌套表格或者合并单元格导致解析异常。把复杂表格拆平再转。文本框里的内容没了文本框在 Markdown 里没有对应结构转换工具通常会忽略。这种情况只能手工把文本框内容抄到正文里。页眉页脚没了这是正常的。Markdown 是内容格式没有页眉页脚的概念。如果这些信息重要得在正文里补一节。我的习惯是转完之后做个抽查随机挑三五个位置对照原 Word 看一遍。全部通读太耗时间抽查能覆盖大部分问题。6.3 排版错乱类问题排版问题不会导致内容丢失但影响可读性。所有标题都变成普通段落样式没规范回到 4.1 节。列表层级全乱Word 里用了手动输入的编号比如自己敲的1.2.而不是自动编号列表。自动编号才能被正确识别成有序列表手敲的数字会被当成普通文本。段落被拆成很多短行--wrap参数没关加上--wrapnone。代码块没有正确标记Word 里的代码通常就是等宽字体的普通段落转换工具无从判断。这个基本只能手工补三个反引号。如果代码量大可以在 Word 侧先给这些段落设一个统一的字符样式转换后再用脚本按特征批量包裹。到处都是星号原文里可能用了大量加粗做强调转出来全是**。适度保留有意义的加粗其余批量清理Markdown 里加粗太多反而失去重点。7. 反向链路Markdown 回 Word、转 PDF、进知识库7.1 Markdown 转 Word 与模板套用方向反过来Pandoc 一样能干pandoc input.md -f gfm -t docx -o output.docx这条命令生成的是默认样式的 Word字体、字号都是通用的。如果你需要套公司模板可以准备一个样式符合要求的.docx作为参考文档pandoc input.md -f gfm -t docx --reference-doctemplate.docx -o output.docx参考文档的作用是把里面定义的标题、正文、表格等样式应用到输出结果上内容还是你的 Markdown 内容。这个技巧在做批量报告生成时特别有用写一套 Markdown 内容配一个模板就能产出格式统一的 Word 文档。如果模板里还需要动态填充数据比如生成带列表的报表单纯靠 Pandoc 就不够了一般会走模板引擎的路子在 Word 里做好占位符程序读取数据后渲染。这也是为什么很多办公自动化项目最后都是Markdown 管内容、模板管格式、程序管批处理这套组合。7.2 转 PDF / HTML 的引擎选择Markdown 转 PDF本质是两步先转成有排版能力的中间格式再交给排版引擎渲染。一条常见路线是走 LaTeXpandoc input.md -f gfm -t pdf --pdf-enginexelatex -o output.pdf用xelatex是为了支持中文字体纯pdflatex处理中文会很麻烦。这条路排版质量高适合正式文档代价是要装一个完整的 LaTeX 发行版体积不小。另一条路线是编辑器插件。很多编辑器提供一键导出 PDF底层用的是浏览器内核或者专门的 HTML 排版引擎。有些插件会依赖额外的排版程序比如需要单独下载一个排版引擎并配置到插件设置里的执行路径如果没配好导出会直接报错。这种情况先看插件的文档确认依赖装没装、路径填没填。还有个轻量路线是先转 HTML 再打印成 PDFpandoc input.md -f gfm -t html5 -s --metadata title文档标题 -o output.htmlHTML 出来后用浏览器打开打印成 PDF。这条路优点是简单、不需要额外引擎缺点是分页控制比较弱。临时用足够正式出版级别的要求就别指望了。7.3 喂给 AI 知识库前的处理思路现在很多人在做 AI 知识库文档解析是绕不开的一环。Word 和 PDF 直接扔进去解析效果往往一般因为这两种格式里混杂了大量版式信息干扰内容提取。我的做法是先把它们统一转成 Markdown再入库。理由很实在Markdown 里结构是显式的标题、列表、表格都有明确标记切分的时候按标题切就行比按页切或者按字符数切合理得多。而且 Markdown 是纯文本token 利用率比带一堆 XML 标签的格式高。转换的时候有个小技巧值得一试先把文档里的页眉、页脚、页码、水印这类重复信息去掉再转。这些东西在检索时全是噪声会让召回结果变得很奇怪。如果是整条流程要自动化可以把它做成一个固定管线监听一个目录有新的 Word 进来就自动转换、清洗、切分、入库。用脚本或者低代码自动化平台都能实现关键是每一步的转换参数固定下来别每次手动调。8. 我踩过的几个坑顺手记下来先记一条关于--extract-media的路径陷阱。我早期做批量转换时把输出文件和 assets 目录放在不同的父目录下结果所有图片引用都失效了。后来才想明白这个参数生成的路径是相对输出文件所在目录计算的输出文件换位置路径含义就变了。现在我的脚本里图片目录一律跟 Markdown 文件同级写死这个约定再没出过问题。再记一条关于--wrapnone必须显式加。我曾经以为默认应该不折行吧结果转出来一段话被切成五六行在编辑器里看着还行一进 Git 就发现 diff 全是碎的一次内容修改产生几十行变动review 的时候眼睛都花了。加上这个参数之后一个段落一行diff 干净得多。这种参数属于不加也能用但让你后期很痛苦的类型值得写进脚本模板里当固定项。还有一条关于公式定界符的选择。我一开始用默认的$转完在本地编辑器里显示正常一发布到网页上全变成原始文本。排查了半天才发现是渲染端没启用数学支持。后来我在发布前会先确认渲染环境需要的话把定界符统一换成更通用的形式或者在页面模板里引入数学渲染库。这类问题的特点是本地看着好好的一上线就露馅只能靠发布前的检查清单兜住。最后说一个流程层面上的心得。我现在的习惯是把转换和清洗拆成两个独立的步骤中间产物保留下来。原因是这两件事的失败模式不一样转换出错是工具和文档结构的问题清洗出错是我的脚本逻辑问题。混在一起做出了问题不知道是哪一层的原因。分开之后转换那一步跑完先抽查一遍确认内容没丢再进清洗环节定位问题时快很多。多存一份中间文件占不了多少空间省下的排查时间远超这点成本。