1. 为什么文档写手迟早绕不开Pandoc1.1 先从一个被问爆的问题说起Typora为什么总提示请安装Pandoc如果你用过Typora大概率见过这个弹窗导出Word或PDF时提示需要安装Pandoc。很多人第一次看到这玩意儿心想我明明装好了Typora怎么还要装个Pandoc是不是捆绑软件我第一次遇到这个提示也是这样。查了一圈才知道Typora本身只负责编辑和预览Markdown真正干格式转换重活的是Pandoc——一个命令行文档转换工具。Typora只是把Pandoc外包过来帮自己完成导出工作。就像你点了份外卖但炒菜的是后厨Typora是前台Pandoc是那个闷头颠勺的厨师。搞清楚这层关系后我花了一下午把Pandoc从头到尾折腾了一遍。用完之后我的结论是Pandoc绝不只是Typora的附庸工具它本身就是文档处理领域的一把瑞士军刀——能把Markdown转成Word、PDF、HTML、LaTeX、EPUB甚至反过来把Word转成Markdown。这篇就把安装、上手、核心用法和踩坑经验一次说清楚。1.2 Pandoc到底能做什么Pandoc的名字来源于Pan-doc取意什么文档都能处理。它的底层逻辑非常直白你给它一个输入格式告诉它一个输出格式它就帮你完成转换。支持格式多到什么程度官方列表里列了三十多种我挑几个常用的列出来感受一下转换方向典型命令使用场景Markdown转Wordpandoc input.md -o output.docx写技术方案、报告交付给用Word的同事Markdown转PDFpandoc input.md -o output.pdf生成正式文档、论文、简历Markdown转HTMLpandoc input.md -o output.html发布到网页、生成离线阅读文件Word转Markdownpandoc input.docx -o output.md把别人发的Word整理进自己的笔记体系HTML转Markdownpandoc page.html -o article.md抓取网页文章转成Markdown存档Markdown转EPUBpandoc book.md -o book.epub制作电子书导入阅读器这还只是基础格式。Pandoc还支持引用文献管理Citeproc、自定义模板Template、过滤器Filter等高级玩法。后面我会详细展开。1.3 谁最需要学Pandoc如果你符合下面任何一个身份Pandoc值得花半小时装好技术博主或内容创作者习惯用Markdown写稿但平台或甲方只收Word。学生和科研人员写论文时需要参考文献自动编号、生成标准格式Pandoc配合CSL样式文件能一键搞定。文档工程师同一份内容要输出多版本在线帮助、PDF手册、Word交付件Pandoc能把工作流归一。笔记党从Notion、Obsidian等工具迁移笔记批量转格式时比手动复制粘贴高效百倍。一句话总结任何被格式转换这件事折磨过的人都值得认识一下Pandoc。2. Pandoc安装那些事三个平台一次说清2.1 Windows安装别用绿色解压版Pandoc在Windows上有两种装法MSI安装包和免安装压缩包。我强烈建议用MSI安装包。理由有两个一是它会自动帮你配置环境变量装完即用二是后续更新时不会出现系统里有两个Pandoc版本的混乱。安装步骤访问Pandoc官方发布页面。找到最新版本对应的windows-x86_64.msi文件下载64位系统选x86_6432位系统选x86现在基本都用前者。双击安装包一路Next。安装完成后打开PowerShell或CMD输入pandoc --version验证。看到类似这样的输出就表示安装成功pandoc 3.1.11 Features: server lua Scripting engine: Lua 5.4 User data directory: C:\Users\你的用户名\AppData\Roaming\pandoc这里多说一句很多教程推荐下载zip解压版然后手动添加PATH。我不推荐这样做。手动配环境变量最大的坑是——你配的路径是解压目录但如果以后你把文件夹移动了位置或删了旧版本环境变量就会指向一个不存在的路径命令直接失效。用MSI安装就不会有这个问题卸载时干干净净。2.2 macOS安装首选HomebrewmacOS上最简单的方式是Homebrew。如果你电脑上没装Homebrew先在终端执行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)然后安装Pandocbrew install pandoc装完同样验证一下pandoc --version如果你的Mac是Apple Silicon芯片M1/M2/M3Homebrew会自动安装arm64版本性能和兼容性都没问题。如果不想用Homebrew也可以去官网下载macOS安装包但更新维护不如Homebrew方便——brew upgrade pandoc一条命令搞定的事手动下载安装还得盯着版本更新。2.3 Linux安装看发行版选命令Debian/Ubuntu系的命令是sudo apt update sudo apt install pandocCentOS/RHEL/Fedora系sudo dnf install pandocArch系sudo pacman -S pandoc特别提示apt或dnf仓库自带的Pandoc版本可能比较旧尤其Debian稳定版经常落后主版本好几年。Pandoc更新迭代很快新版本会修掉不少格式兼容的bug。如果你对版本敏感建议下载官方Linux二进制包放到/usr/local/bin下# 下载 tar.gz 包 wget https://github.com/jgm/pandoc/releases/download/版本号/pandoc-版本号-linux-amd64.tar.gz # 解压 tar xvzf pandoc-版本号-linux-amd64.tar.gz # 把可执行文件复制到系统路径 sudo cp pandoc-版本号/bin/pandoc /usr/local/bin/2.4 验证安装是否成功的三个检查点很多人装完Pandoc后直接在Typora里点导出发现还是提示找不到Pandoc。这时候不是没装上而是Typora没找到它。有三个检查点第一确认环境变量路径。在终端输入where pandocWindows或which pandocmacOS/Linux确认返回的路径是Pandoc安装目录。如果返回未找到说明PATH配置有问题。第二重启Typora。Typora是在启动时扫描并识别Pandoc的如果你先开了Typora再装Pandoc它不会实时发现。关掉Typora再重开基本就能解决。第三检查Typora导出偏好设置。在Typora的偏好设置里找到导出确认没有禁用PDF或Word导出功能。有些精简版Typora会阉割导出功能这跟Pandoc无关。3. 十分钟上手从第一条命令开始理解Pandoc的工作逻辑3.1 最简单的文件转换命令Pandoc最基础的用法就一条命令pandoc 输入文件 -o 输出文件注意-o是输出参数output后面跟目标文件名。Pandoc能根据文件扩展名自动判断输出格式所以你不需要额外告诉它我要转成Word——-o result.docx它就知道了。我写Markdown文稿时的最常用命令# Markdown转Word pandoc article.md -o article.docx # Markdown转HTML带目录 pandoc article.md -o article.html --toc # Markdown转PDF需要有LaTeX引擎后面细说 pandoc article.md -o article.pdf可能有朋友要问Pandoc转换出来的Word文档和我在Word里手动排版出来的效果一样吗答案是不完全一样。Pandoc的转换逻辑是还原内容结构不是还原视觉样式。它会正确识别标题、段落、列表、表格、代码块等语义结构但字体、颜色、间距等视觉细节需要靠模板控制。这就像搬家——Pandoc把你的家具内容完整搬进新房子Word模板但每件家具摆在哪、墙上刷什么颜色是你自己的事。3.2 输出带样式的Word文档reference-doc参数Pandoc转出来的Word默认样式非常朴素标题是蓝色的正文是默认字体表格边框也不够精致。如果你的需求是转出来的docx直接能发给客户/领导看不需要我再手动调那必须用到reference-doc参数。原理是这样的Pandoc支持用一个现成的Word文档作为样式参考模板。它会从这个模板里读取样式定义标题格式、正文字体、表格样式等套用到转换结果上。操作步骤第一步生成默认参考模板pandoc -o custom-reference.docx --print-default-data-file reference.docx这里会生成一个custom-reference.docx文件这个文件本身是个样式模板空壳。第二步修改模板样式用Word打开这个文件手动修改里面的标题1、标题2、正文、表格等样式。比如把标题改成黑体、正文行距调成1.5倍。保存关闭。第三步使用模板转换pandoc article.md -o article.docx --reference-doccustom-reference.docx对比前后的docx文件你会明显发现排版质量上了一个档次。这一步做一次后续一直受益建议每个经常用Pandoc转Word的人都花十几分钟定制一个自己的参考模板。3.3 批量转换Markdown文件到Word写文档遇到批处理需求很常见比如要把一个目录下所有Markdown转成Word。先分享一个Windows PowerShell下的做法Get-ChildItem C:\docs\*.md | ForEach-Object { pandoc $_.FullName -o $($_.FullName -replace \.md$, .docx) }macOS/Linux下的bash版本for f in /path/to/docs/*.md; do pandoc $f -o ${f%.md}.docx done这样批量转换能把一分钟只能转一个文件的重复劳动压缩成几秒钟跑完。自己手动操作时注意统一命名规范别让输出文件和源文件重名覆盖。3.4 理解Pandoc的命令结构参数分类记忆法接触Pandoc时间长了会看到很多奇奇怪怪的参数容易懵。我的经验是把它们分成四类记忆参数类别典型参数作用输入输出控制-o、-f、-t指定输出文件、强制指定输入/输出格式结构控制--toc、--number-sections设置目录、标题自动编号样式控制--reference-doc、-V fontsize12pt控制输出样式、PDF变量高级功能--filter、--citeproc调用过滤器、处理文献引用这样理解后看到一条陌生的Pandoc命令你至少能判断它是在控制什么层面的事。后面遇到不认识的参数也能自己举一反三去搜文档。4. Pandoc真正值钱的地方进阶工作流4.1 PDF输出背后的引擎选择LaTeX与wkhtmltopdf前面提到Markdown转PDF需要额外的引擎这里展开说说。Pandoc本身不生成PDF它只负责生成中间格式通常是LaTeX或HTML再由其他工具把中间格式渲染成PDF。Pandoc的PDF转换有几种引擎路径方案一LaTeX引擎xelatex / pdflatex / lualatex这是最常用最成熟的方式。安装方法按平台区分——Windows装MiKTeXmacOS装MacTeX体积大或BasicTeX精简版Linux用apt装texlive-xetex texlive-lang-chinese等包。安装完成后用下面的命令转换PDFpandoc article.md -o article.pdf --pdf-enginexelatex为什么推荐xelatex而不是pdflatex因为xelatex对中文的支持更好能直接用系统字体。pdflatex处理中文需要额外的宏包配置容易踩坑。如果你的文档是中英混排无脑选xelatex。方案二HTML引擎wkhtmltopdf / weasyprint / princePandoc把Markdown先转成HTML然后用webkit内核的wkhtmltopdf渲染成PDF。好处是不用装几GB的LaTeX发行版坏处是对复杂结构比如长表格、交叉引用的支持不如LaTeX优雅。pandoc article.md -o article.pdf --pdf-enginewkhtmltopdf两条路怎么选纯文本、技术文档、学术论文优先LaTeX方案明显的网页风格美化需求、追求安装体积小才考虑HTML方案。我用过一段时间wkhtmltopdf后来还是回归了xelatex因为生成的PDF排版更紧凑、页边距和字号控制更精细。4.2 学术写作利器文献引用与参考文献格式化Pandoc内置了Citeproc文献处理系统配合CSL样式文件可以像LaTeX的BibTeX那样管理参考文献。我第一次用这个功能时惊喜不小——这意味着写论文时我可以在Markdown里直接[key]引用文献然后让Pandoc自动生成标准格式的参考文献列表。工作流长这样第一步准备BibTeX格式的文献库references.bibarticle{knuth1984literate, title{Literate Programming}, author{Knuth, Donald E.}, journal{The Computer Journal}, volume{27}, number{2}, pages{97--111}, year{1984} }如果手上没有BibTeX文件可以先用Zotero或Mendeley管理文献然后导出为BibTeX格式。第二步在Markdown中插入引用Knuth提出的文学编程范式 [knuth1984literate] 对后续文档理念影响深远。第三步用Pandoc转换自动格式化文献pandoc thesis.md -o thesis.docx --citeproc --cslieee.csl --bibliographyreferences.bib其中--cslieee.csl指定格式风格。不同学科投稿要求不同的参考文献格式CSL文件是标准化的可以去Zotero样式仓库下载。想用GB/T 7714国标格式就下载对应的CSL文件。把这一段的操作连起来看一套纯文本驱动的论文写作流程就跑通了Markdown写内容、BibTeX管文献、CSL管格式、Pandoc管转换。不再依赖Word里那套动不动卡死的插入引用-更新域。4.3 自定义模板控制输出格式的终极手段前面用reference-doc控制Word样式其实Pandoc还有更底层的方式——模板Template。模板决定Pandoc生成目标格式时的整体骨架结构。比如生成的HTML文件head里放什么、正文结构怎么排都由模板控制。查看当前默认模板pandoc -D html这会打印出内置的HTML模板源码。想自定义就把这个源码存成一个文件修改后通过--template参数指定。比如我想给自己的HTML导出加一个页脚版权声明可以在模板的body标签后面插入一段HTML。模板机制刚接触时有点门槛但学会后对输出完全受自己掌控这件事的信心会大幅提升。如果你只想要一个特定页面样式直接改模板比每次转换后再去后期处理高效得多。4.4 过滤器给Pandoc加装外挂Pandoc的高级玩法之一是过滤器Filter它可以让你在文档中间节点上做程序化处理。一句话解释Pandoc把Markdown解析成抽象语法树AST过滤器可以在这个语法树上做修改然后再继续转成目标格式。举一个最实用的例子让Markdown里的代码块自动添加行号。-- line-number.lua function CodeBlock(block) local lines {} for i, line in ipairs(block.text:lines()) do table.insert(lines, tostring(i) .. | .. line) end block.text table.concat(lines, \n) return block end然后运行pandoc code.md -o code.html --lua-filterline-number.lua这样输出的代码块每行都有行号前缀省去前端JS高亮插件依赖。Pandoc的Lua过滤器是它生态中最强大的扩展机制之一。常见用途还包括统一图片宽度、自动给外部链接加target_blank、过滤掉特定类型的段落、生成自定义交叉引用等。5. 我踩过的坑与解决经验5.1 中文PDF输出的字体问题这是Pandoc新手最容易碰到的问题。用xelatex转中文PDF时如果出现Missing character空白字或一堆方块字多半是字体没找到。解决办法是在命令中显式指定中文字体pandoc article.md -o article.pdf --pdf-enginexelatex -V mainfontNoto Serif CJK SC -V sansfontNoto Sans CJK SC -V monofontNoto Sans Mono CJK SCWindows系统可以把主字体设为SimSun宋体、黑体等系统自带字体。macOS可以设为Songti SC、PingFang SC。还有一个更省心的方案在Markdown文件头部通过YAML定义变量--- mainfont: Noto Serif CJK SC sansfont: Noto Sans CJK SC monofont: Noto Sans Mono CJK SC geometry: margin2.5cm ---在正文之上用YAML块声明文档级变量比每次敲一长串命令参数清爽得多。5.2 图片路径失效与日期格式的坑Markdown里引用图片如果用的是相对路径在转成docx或PDF时可能丢失。原因是Pandoc的工作目录和Markdown所在目录不同。解决方式是习惯用--resource-path参数pandoc article.md -o article.docx --resource-path./images更稳妥的做法是在文件头YAML中设置--- resource-path: [., ./images] ---另外Pandoc解析Markdown里的日期时默认要求ISO 8601格式YYYY-MM-DD。如果你用2024年1月15日这种中文习惯表达部分模板会解析不出正确的日期对象。需要中文日期显示时可以在YAML中直接写字符串变量避开语义化解析。5.3 复杂表格与脚注的处理Pandoc对简单表格行列规整的示例表格支持很好但遇到合并单元格、跨行跨列的复杂表格原生的Markdown表格语法根本无法表达。我的处理建议分两种内容必须以Word交付且表格复杂用HTML表语法嵌入Markdown来写——Pandoc会识别Markdown里嵌入的HTML标签table tr td rowspan2跨两行/td td单元格A/td /tr tr td单元格B/td /tr /table如果源文档本来就有复杂表格就用Pandoc的docx转markdown方向能力先看看能否反转保留结构不行就直接把这部分内容放到附件不加进Markdown转换流。脚注的问题相对小一些Pandoc原生支持[^1]形式的脚注标记转成Word时会自动生成Word脚注格式转HTML时会生成规范的脚注链接基本零坑。5.4 Pandoc与Typora协作的隐藏细节Typora是Pandoc最常见的前端入口之一。配合使用时有几个细节值得留意图片路径如果Markdown文档里的图片是相对路径而Typora的偏好设置里图片复制到路径选项填的是./${filename}.assets这类相对目录转Word时图片可能因为路径找不到而丢失。解决方法是在Typora的偏好设置中开启优先使用相对路径并保证导出前图片确实存在。自定义语法兼容性Typora有一些自己的扩展语法比如高亮、~~删除线~~、TOC标签Pandoc默认不支持部分扩展语法。层级产品自己有兼容策略但如果转出效果不对可以先排查是不是Typora私货语法在捣乱。导出PDF差异Typora内嵌的导出PDF功能File Export PDF用的是Typora自己的渲染器和Pandoc导出是完全两条路径。代码块高亮、主题风格在两条路径下表现不同别混为一谈。想要Pandoc风格的PDF输出应该走Typora里的Export Pandoc选项或直接用命令行。6. 玩法拓展Pandoc还能这样用6.1 用Pandoc做批量文档格式梳理写笔记时间长了文件夹里各种格式文件混在一起——有的.md、有的.txt、有的.docx。整理归档时把它们统一转成Markdown放笔记系统里很常见pandoc notes/old.docx -o notes/old.md注意如果是带批注、修订痕迹的Word文件转Markdown会丢掉这些信息。但常规内容的时序、标题结构能很大程度保留足够日常归档使用。6.2 与Obsidian/Notion联动Obsidian等知识库工具都基于MarkdownPandoc可以作为扩展出口。把Obsidian里的笔记导出成Word或者从网页复制一整篇文章先存成HTML再用Pandoc转成Markdown——这个工作流特别适合沉淀阅读素材。举个例子看到一篇排版乱七八糟但内容不错的网页文章用浏览器另存为HTML然后pandoc article.html -o article.md --wrapnone--wrapnone让输出文本不自动换行Obsidian里阅读体验更好。再手动删掉一些广告区块一篇净化的网页读书笔记就进了自己的知识库。6.3 Pandoc与版本控制的搭配Markdown最大的优势是纯文本配合Git等版本控制工具可以追踪每次修改。Pandoc的存在让这套工作流可以延伸同一个Markdown文件需要正式交付时用Pandoc生成docx或PDF需要预览时生成HTML全部从单一源文件派生。这样每次更新只改一处然后重新跑一遍脚本所有输出文件自动sync。我自己的一个小项目就是这个思路一篇周报用Markdown维护一个build.sh脚本负责通过Pandoc生成docx发给领导、生成HTML发到内网、生成PDF归档。整个过程不到3秒。7. 写在最后从会用到离不了Pandoc这个工具最奇妙的地方在于——它不像一个花哨的神器更像一把朴实的螺丝刀。刚开始用你只会拿它拧个螺丝转个格式用久了才发现修电脑、装柜子、拆玩具到处都会想用它。我个人最深的体会是Pandoc解决的不仅是格式转换这个操作层面的问题它还改变了我的写作工作流。以前我在Word里写方案写一半就得停下手动调整格式现在我在Markdown里写格式是最后交给Pandoc统一处理的事。这种内容和排版分离的思路减轻了不少心力消耗。最后再分享一个小技巧把常用命令存成shell脚本或alias比如我自己的~/.bashrc里有一条alias md2docxpandoc --reference-doc$HOME/.pandoc/reference.docx --toc --toc-depth2以后写文档只需要输入md2docx input.md -o output.docxPandoc会配上我预制的样式模板、自动生成目录。真正把流程打磨成一条命令走天下的状态。希望这篇能帮你把Pandoc真正用起来。装上它花点时间定制好模板后面每次转换都是省下来的时间。