Pandoc 实战：一条命令把 Markdown 转成 Word、PDF 和网页，文档工作流一次讲透

大家好，我是 IT 大叔。今天不聊服务器，聊一个更”日常”却同样让人头疼的活儿——写文档。相信不少人和我一样，有过被 Word 排版折磨到凌晨的经历，也踩过 PDF 里中文乱码的坑，更头疼过同一份内容要在 Word、网页、博客之间来回复制粘贴、反复排版。今天给你介绍一个”文档界瑞士军刀”：Pandoc。它能让你用最顺手的 Markdown 写稿，然后一条命令变成 Word、PDF、网页、甚至 PPT，全程命令行、可脚本化、可复现。

一、为什么你需要 Pandoc

Pandoc 是一个开源的”万能文档转换器”，由 Haskell 写成，支持几十种格式互相转换。它的价值不在”能转”，而在“可脚本化”：一旦你把文档源文件用 Markdown 管理起来，改一次源文件、重新跑一遍命令，Word、PDF、网页三个版本就一起更新了。对我这种既要写技术文档、又要交汇报、还要发博客的人，一套源文件打天下，比同时维护三份格式的文件省太多事。而且配合 Git，你的文档就变成了”代码”——可版本管理、可回溯、可自动生成。

二、安装 Pandoc

Pandoc 跨平台，安装都很简单，三行命令对应三大系统。

# Ubuntu / Debian
sudo apt install pandoc

# macOS
brew install pandoc

# Windows
winget install --id JohnMacFarlane.Pandoc

装完验证一下版本，能输出就说明装好了：

pandoc --version

三、三种基础转换，先跑通

假设你已经有一个 report.md 文件，最基础的用法就是这几种：

# 转 Word
pandoc report.md -o report.docx

# 转网页
pandoc report.md -o report.html

# 转 PDF
pandoc report.md -o report.pdf

前两个几乎零依赖，转出来就能用。PDF 会特殊一点，我们下一节单独讲它的坑。

四、中文 PDF 的坑：必须配 LaTeX 引擎

Pandoc 转 PDF 默认走 LaTeX 引擎，而默认引擎 pdflatex 对中文支持很差，直接转出来要么乱码、要么缺字。正确做法是装一个支持中文的引擎 xelatex，并显式指定中文字体。

# Ubuntu 下安装 xelatex 引擎 + 中文字体
sudo apt install texlive-xelatex texlive-lang-chinese fonts-noto-cjk

转换时指定引擎和中文字体：

pandoc report.md -o report.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Noto Sans CJK SC"

这里的 -V CJKmainfont 就是给 xelatex 指定正文中文字体，装上 Noto Sans CJK 这套字体，中文 PDF 就能正常显示了。如果你想要衬线体，可以换成 "Noto Serif CJK SC"。

五、YAML 头部与常用参数

你可以在 md 文件最前面加一段 YAML 元数据，用来填标题、作者、日期：

---
title: "项目周报"
author: "IT大叔"
date: "2026-09-21"
---

再配合几个常用参数，生成的文档就”有模有样”了：

• --toc：生成目录，--toc-depth=2 控制目录层级
• --number-sections：给章节自动编号
• --highlight-style=tango：代码高亮风格（可选 pygments、kate、monochrome）
• -V geometry:margin=2cm：控制 PDF 页边距

把它们组合起来，就是一条”生产级”转换命令：

pandoc report.md -o report.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Noto Sans CJK SC" \
  --toc --toc-depth=2 --number-sections \
  -V geometry:margin=2cm

六、定制你的文档样式

默认转换出来的文档样式偏”素”，但可以完全定制。先说 Word：先生成一个默认参考文档，用 Word 打开改里面的字体、标题颜色、页眉页脚，然后指定它即可。

# 生成默认参考文档
pandoc --print-default-data-file reference.docx > custom.docx

# 指定自定义样式转换
pandoc report.md -o report.docx --reference-doc=custom.docx

网页同理，用 --standalone 生成带完整头的 HTML，再挂上自己的 CSS：

pandoc report.md -o report.html --standalone --css=style.css

七、批量转换脚本

目录下如果积压了一堆 md 要转，写个循环一次搞定：

for f in *.md; do
  pandoc "$f" -o "${f%.md}.docx"
done

进阶一点，还可以用 Makefile 把”源文件 → 成品”的依赖关系写清楚，改哪个文件就只重新生成哪个文件，效率拉满。

八、写在最后

Pandoc 最大的价值，是把你从”排版”这件重复劳动里解放出来，把精力放回内容本身。Markdown 写源文件、命令生成成品，这套工作流我用了好几年，越用越顺手。如果你也正在被文档格式来回折腾，强烈建议花半小时把上面的命令跑一遍，从此告别”一份文档改三遍”的噩梦。有踩坑的，欢迎评论区聊聊。