从纯文本生成 docx/pdf：难点从来不在“转换”两个字

转出来很容易，转得像人写的很难

很多工具都能把纯文本变成 docx 或 PDF。Markdown 一行 pandoc input.md -o output.docx 就跑通；LaTeX 用 xelatex paper.tex 也能直接出 PDF；Typst 一句 typst compile report.typ 同样能拿到结果。

第一次跑通的时候，人很容易产生错觉：就这？不就是把一种文本格式换成另一种格式吗？

真到项目里用，麻烦马上来了。标题层级不对，表格撑破页面，代码块换行难看，中文字体忽大忽小，图片路径失效，目录页码对不上。客户打开 Word 一看，说：“这不像正式文档。”这句话杀伤力很大，因为它说不出具体 bug，却让人知道系统还没过关。

我的判断是：从纯文本生成 docx/pdf，真正的难点不在“转换”这一步，而在“源格式选型 + 样式契约 + 输出链路 + 工程化”的整体设计。

纯文本擅长表达结构，Word 和 PDF 更关心呈现。一个偏语义，一个偏排版。二者之间不是一条直线，而是一座桥。桥修得粗糙，能过人；桥修得可靠，才敢过车队。

1. 别只盯着 Markdown：源格式有六种常见选择

聊文档生成，很多人默认源就是 Markdown。其实 Markdown 只是“轻量易写”的代表，并不总是最佳源格式。把视野放宽一点，常见的纯文本源大致有六种：

一个很关键的判断：给人写的源格式（Markdown、AsciiDoc、reST、LaTeX、Typst）和给系统存的源格式（JSON）可以分开。

很多团队的错误是把 Markdown 既当“用户写的格式”，又当“系统的真相”。结果两边都委屈：用户想要的复杂版式 Markdown 表达不了，系统又被迫在 Markdown 字符串上做各种正则补丁。更稳的做法是：用户在前端用合适的方式编辑，系统底层存 JSON，导出时再选合适的源/中间格式。

2. 三层视角：内容、样式、版式

无论源格式是哪种，从纯文本到 docx/pdf，本质上是三层映射：

Markdown 主要解决内容层，样式层只给一点暗示，版式层几乎不管。AsciiDoc 和 reST 在内容和样式层比 Markdown 走得更远，版式还是要靠下游引擎。LaTeX 和 Typst 直接管到版式层，但代价是学习成本和语法重量。

工具可以帮你完成基础转换，但工具不会替你定义“什么叫好看的公司文档”。这部分必须工程化。

3. 难点一：样式契约，不是语法替换

很多人一开始会把问题想简单：# 变成标题一，## 变成标题二，代码块变成等宽字体，表格变成 Word 表格。

这只能算入门。

真正的文档系统需要一张清晰的样式契约：

如果没有这张契约，同一篇源文本这次转出来像技术方案，下次转出来像会议纪要。工具没错，是你没有把文档品味写成规则。

Pandoc 的 reference.docx、LaTeX 的 documentclass 和包、Typst 的 template 函数，本质都是同一件事：把视觉规范沉淀成可复用资产。没有这个资产，再快的转换工具也救不了你。

一句话：不要让转换工具自由发挥。文档系统也需要设计规范。

4. 难点二：源格式表达力 vs 出版级需求

源格式越轻，越好写；写得越多，越容易撞到天花板。

下面这些需求，在 Markdown 里都不算原生强项：

• 这张表格希望横向展示，另一张表格希望自动换行。
• 某个二级标题前必须分页。
• 这段文字需要放进提示框，而不是普通引用。
• 图片需要编号，正文里要引用“图 3”。
• 代码块要显示文件名，还要带行号。
• 生成 PDF 时要有封面、目录、页眉页脚和水印。
• 数学公式、化学式、电路图必须排得整齐。

硬塞进 Markdown，就会出现各种方言：自定义 HTML、YAML front matter、短代码、容器块、特殊注释。

---
title: 系统设计说明
doc_type: design
template: zoom-design-v1
toc: true
watermark: internal
---

::: warning
这部分只适用于内部系统，不建议公开发布。
:::

<!-- pagebreak -->

这没有问题，但它意味着你已经不只是“支持 Markdown”，而是在设计一门轻量文档 DSL。DSL 一旦出现，就要考虑版本、兼容、校验、错误提示和迁移。

老程序员看到这里心里会一紧：又来了，一个看似简单的小工具，最后长成了平台。

所以遇到表达力不够的场景，有两条路可以选：

1. 换更强的源格式：AsciiDoc、reST、LaTeX、Typst，本身就是为复杂文档设计的，省下你造方言的时间。
2. 换存储模型：源不是给人写的字符串，而是结构化 JSON。前端做合适的编辑器，后端按需输出多种格式。

判断标准很简单：如果一份文档里有 10 个以上 Markdown 方言扩展，往往说明源格式选错了。

5. 三大输出链路：Word 模板、HTML+CSS、TeX 引擎

很多系统会把 docx 和 PDF 放在一起说，好像它们只是两个输出格式。工程上最好别这么想。

docx 是可编辑文档，用户会下载后继续修改。PDF 是最终展示文档，用户通常期待“我看到什么，别人打开也是什么”。这两个目标不同，技术路线也不同。

常见的输出链路有三类：

如果系统是“在线编辑 + 在线预览 + 导出 PDF”，更稳的方式是把 HTML 预览链路设计清楚，再用浏览器渲染能力生成 PDF。预览和导出离得近，沟通成本低。

如果客户强依赖 Word 模板，尤其是公司报告、合同、标书、设计文档，docx 模板链路就绕不开。这条路适合用 docxtemplater、docx.js、python-docx、docx4j 或 Open XML SDK，把结构化数据填进预定义的 Word 模板，PDF 再通过 LibreOffice、ONLYOFFICE 或 Chromium 转换。

如果文档对版式要求很高，例如学术论文、教材、白皮书、对外发布的报告，TeX 引擎或 Typst 是更合适的选择。下面单独展开 LaTeX。

6. 单独说 LaTeX：什么时候值得，怎么用

LaTeX 在工程圈名声两极。学过的人一般有两种反应：要么说“早该用它”，要么说“再也不想碰”。两边都有道理。

6.1 LaTeX 真正擅长什么

• 复杂数学公式、化学式、算法伪代码、电路图、乐谱，几乎没有对手。
• 大型文档结构：书籍、博士论文、教材、技术手册，跨章节引用、参考文献、索引体系完整。
• 自动化排版：分页、孤行寡行、浮动元素位置、对齐和断行，引擎会替你做大量决定。
• 字体和排版精度：行距、字距、连字、字号体系是出版级的。

简而言之，当文档接近“图书 / 论文 / 出版物”时，LaTeX 仍然是版式天花板。

6.2 LaTeX 的痛点也很真实

• 学习曲线陡：宏、包、环境、计数器、长度单位，新手两周都未必能从容应付。
• 错误提示不友好：一个 Missing $ inserted. 经常要翻三页文档。
• 包冲突：hyperref、xcolor、geometry 这些常用包的加载顺序很敏感。
• Web 集成不容易：浏览器里没有原生 LaTeX，需要服务端编译或前端用 KaTeX/MathJax 只渲染数学部分。
• 中文支持要选对引擎：传统 pdflatex 处理中文吃力，现实里更多用 XeLaTeX 或 LuaLaTeX。

6.3 中文 LaTeX 的几条经验

如果文档以中文为主，建议：

• 用 XeLaTeX 或 LuaLaTeX，原生支持 Unicode 和系统字体。
• 用 CTeX 套件或 ctex 文档类，省掉很多中文配置坑。
• 字体提前固定：正文用宋体，标题用黑体，等宽用一款系统都装得到的字体（例如 Source Han Sans、Source Han Serif、Source Code Pro）。
• 镜像内置字体，构建容器里放好，不要依赖宿主机字体。
• 写一份最小可编译模板，跑通后再加内容，不要一开始就抄一份复杂模板。

一个能用的最小例子：

\documentclass[12pt]{ctexart}
\usepackage{geometry}
\usepackage{hyperref}
\geometry{a4paper, margin=2.5cm}

\title{年度技术评审报告}
\author{Walter Fan}
\date{\today}

\begin{document}
\maketitle
\tableofcontents

\section{概览}
本年度评审覆盖三条业务线，重点关注稳定性、性能与成本。

\section{关键指标}
\begin{itemize}
  \item 可用性：99.95\%
  \item 平均时延：120ms
  \item 单位成本下降：18\%
\end{itemize}

\end{document}

6.4 在 Web 系统里怎么集成 LaTeX

直接让前端跑 LaTeX 不现实，常见做法有三种：

1. 服务端编译：用户提交源文件或片段，后端容器里跑 xelatex，再把 PDF 返回。这条路最完整，但要管好资源限制、超时和并发。
2. 数学公式前端渲染：正文用 Markdown / AsciiDoc，公式部分用 LaTeX 语法，浏览器里用 KaTeX 或 MathJax 实时渲染。覆盖 80% 的“只是写写公式”场景。
3. 混合模式：编辑用 Markdown + 公式，导出 PDF 时把 Markdown 转 LaTeX，再走 xelatex。Pandoc 在这条链路上很顺手。

判断很简单：只是想写公式，用 KaTeX/MathJax 就够；要做完整出版级文档，老老实实上服务端 LaTeX 或 Typst。

6.5 Typst 值不值得切？

Typst 是近几年崛起的现代排版系统，语法更接近脚本语言，编译速度快，错误信息友好很多，PDF 输出质量也不错。

我的看法是：

• 如果是新项目，Typst 值得评估，尤其是报告、白皮书、内部技术文档。
• 如果是老项目、已经积累了大量 LaTeX 模板和参考文献库，迁移成本不小，没必要为切而切。
• 出版社、期刊、学术圈对 LaTeX 的支持仍然是主流，重投稿场景目前还是 LaTeX 更稳。

7. Web 在线系统的工程难点

命令行转换是单机问题。Web 在线编辑和导出，是系统问题。

一个最小可用架构通常长这样：

1. 前端提供编辑器、预览和导出入口。
2. 后端保存源内容、资源文件和文档元数据。
3. 转换服务把源渲染成 docx/pdf。
4. 任务队列处理较慢的导出任务。
5. 对象存储保存生成结果。
6. 前端轮询或通过 WebSocket 接收导出状态。

看起来朴素，实际每一层都有坑。

7.1 编辑器：纯文本还是 WYSIWYG

如果只给工程师用，纯文本编辑器加预览就够了：左边写 Markdown / AsciiDoc，右边看 HTML 预览。

如果给非技术用户用，事情就变复杂。用户会期待：

• 选中文字点一下变粗。
• 拖拽图片自动上传。
• 表格可以像 Excel 一样增删行列。
• 粘贴 Word 内容时格式不要全丢。
• 回车、缩进、列表编号要符合直觉。

这时通常要 WYSIWYG 编辑器，比如基于 ProseMirror、Tiptap、Lexical、BlockNote 的方案。但这里有个老问题：编辑器内部模型、纯文本源、导出文档三者是否能无损互转？

答案通常是：很难。

所以产品上要做取舍。面向工程师，可以牺牲一点所见即所得；面向普通办公用户，就要牺牲一点纯文本的纯粹性，把核心存储模型放到 JSON 上。

7.2 资源管理：图片不是一行链接那么简单

本地写 ![架构图](./images/arch.png)，到了 Web 系统里，问题立刻变多：

• 图片上传到哪里？
• 用户是否有权限访问？
• 导出时转换服务能否读到？
• 图片太大是否要压缩？
• 删除文档时资源是否清理？
• 历史版本引用的图片还能不能打开？

如果支持粘贴截图，资源管理更要提前设计。否则半年之后，存储桶里全是孤儿图片，谁也不敢删。

7.3 导出任务：不要在 HTTP 请求里硬等

小文档几秒钟能转完，大文档就不好说了。一旦里面有几十张图片、复杂表格、代码高亮、目录生成，再赶上并发导出，HTTP 请求里同步等待很容易超时。

更稳妥的做法是异步任务：

用户点击导出
  -> 创建 export_job
  -> 返回 job_id
  -> 后台 worker 转换
  -> 保存 docx/pdf
  -> 更新 job 状态
  -> 前端提示下载

这听起来像常识，但很多“先做个小工具”的系统，第一版都容易偷懒。偷懒不是罪，偷懒后忘了还债才是。

7.4 安全：纯文本也是外部输入

源文本看起来是普通字符串，但只要它能进入渲染器、文件系统、命令行或 HTML 页面，就必须当外部输入处理。

典型风险包括：

• Markdown 中嵌入 HTML，导致 XSS。
• 图片链接指向内网地址，触发 SSRF。
• 文件路径里带 ../，读取到不该读的文件。
• LaTeX 的 \write18 或 \input{} 在没限制的引擎里能执行命令、读任意文件。
• 转换命令拼接用户输入，变成命令注入。
• 用户上传超大图片或复杂文档，拖垮 worker。

基本原则：

• 禁止或严格过滤危险 HTML。
• 外链图片做 allowlist 或代理下载限制。
• 文件路径规范化，拒绝目录穿越。
• LaTeX 编译必须关闭 shell-escape，限制 \openin / \openout 等危险原语。
• 调用转换工具时使用参数化 API，不拼 shell 字符串。
• worker 运行在沙箱里，限制 CPU、内存、磁盘和超时时间。

文档系统看起来温柔，安全问题一点也不温柔。

7.5 一致性：预览、docx、PDF 三份结果容易打架

用户最烦的是：Web 预览看起来很好，导出 PDF 后换行变了；PDF 没问题，docx 打开后目录样式又不对。

解决思路不是承诺“完全一致”。这话最好别轻易说。更现实的做法是定义一致性边界：

• 正文结构必须一致。
• 标题层级和目录必须一致。
• 图片和表格不能丢。
• PDF 以预览或出版引擎为准，docx 以模板样式为准。
• 对分页、换行这类细节，提前写进产品说明。

7.6 字体和国际化

中文字体、英文等宽字体、粗体效果、标点换行、代码块里的中英文混排，都可能影响最终版式。PDF 导出尤其依赖运行环境里的字体。如果服务器没有对应字体，结果可能变成方块字，或者被替换成另一种字体。

工程纪律就几条：

• 明确支持哪些字体。
• 在容器镜像里打包字体。
• 模板里固定中英文字体。
• 用包含中文、英文、代码、表格、图片、公式的样本文档做回归测试。

7.7 协作：多人编辑比导出更难

如果只是“一个人写，点一下导出”，难度还可控。

多人在线编辑会让问题升级：谁正在编辑哪一段？两个人同时改同一行怎么办？历史版本怎么保存？评论和批注如何映射回源格式？导出的 docx 是否要包含修订记录？权限按文档、目录还是组织空间？

这已经不再是“纯文本转 docx”，而是协作文档产品。底层可能要考虑 OT 或 CRDT，至少也要有版本快照和冲突处理策略。

别轻易把“在线编辑”四个字写进需求。它像一个小门，推开后面是另一栋楼。

8. 简历生成：别把 Markdown 当核心存储

如果场景换成“在线生成简历”，建议会更明确：不要把 Markdown 当核心存储格式。

简历不是普通文章。它结构很固定：基本信息、工作经历、项目经历、教育背景、技能、证书、语言、作品链接。它真正难的地方也不是“写几段文字”，而是一页或两页内的版式控制、ATS 解析友好、模板切换、PDF 所见即所得。

这时更合适的链路是：

扩展版 JSON Resume
  -> 表单字段 + 局部富文本 JSON
  -> HTML/CSS 实时预览
  -> Playwright / Puppeteer 调 Chromium 生成 PDF
  -> docx 作为次要导出能力

JSON Resume 的价值在于它用 JSON Schema 定义了简历结构。可以把它当作底座：标准字段沿用，业务需要的字段再扩展，比如求职方向、目标岗位、项目亮点、关键词、隐私开关、不同版本的投递记录。

编辑层不必做成 Google Docs。简历更适合“表单 + 局部富文本”：

这样做的好处是，用户专心写内容，系统负责排版。模板用 React/Vue 组件实现，预览就是 HTML/CSS，导出 PDF 时用 Playwright 或 Puppeteer 调 Chromium。只要服务端字体、页面尺寸、CSS 和 Chromium 版本固定，预览和 PDF 的差异就比较容易控制。

docx 可以做，但放在第二优先级。原因很现实：简历的主交付物通常是 PDF，docx 更多是“对方要求可编辑版本”时的补充。docx 生成可以走两条路：

• 模板优先：用 docxtemplater 这类工具，把 JSON 数据填进预定义 Word 模板。
• 代码生成：用 docx.js 直接生成段落、表格、样式和链接。

无论哪种，都别试图让 docx 和 PDF 完全一模一样。PDF 以 HTML/CSS 预览为准，docx 以 Word 模板可编辑性为准。边界说清楚，后面少很多扯皮。

一句话：简历生成应该是结构化文档系统，不是自由排版系统。自由排版看上去高级，最后常常变成用户亲手把自己的简历排坏。

9. 怎么选路线：一个简化决策树

文档生成最容易犯的错，是还没想清楚目标，就开始比较工具。第一步应该问：你最怕哪件事失控？

可以按下面这棵决策树先粗分：

你最关心什么？
├─ docx 必须符合公司模板
│  └─ 结构化 JSON（ProseMirror / Tiptap / 自定义 schema）+ docx 模板
├─ PDF 排版质量最高
│  └─ LaTeX / Typst / HTML + CSS Paged Media
├─ 技术文档结构能力
│  └─ AsciiDoc / reStructuredText + Sphinx / DocBook / DITA
├─ 一份源文件生成多种格式
│  └─ Pandoc AST 作为中间层
└─ 在线编辑 + 多种导出
   └─ 结构化 JSON 为核心 + 多条输出链路

各条路线的要点：

如果你最关心 docx 符合公司模板，Markdown 通常不是最佳源格式。更稳的路线是：

• 用结构化 JSON、ProseMirror JSON 或 Tiptap JSON 存内容。
• 用 docx 模板作为版式真相。
• 通过 docxtemplater、docx.js、python-docx、docx4j 或 Open XML SDK 生成 docx。
• PDF 再通过 LibreOffice、ONLYOFFICE 或 Chromium 转换。

如果你最关心 PDF 排版质量，就别只盯着 docx：

如果你最关心 技术文档结构能力，可以考虑：

• AsciiDoc：admonition、include、属性、交叉引用，适合技术手册。
• reStructuredText + Sphinx：适合文档站、API 文档、交叉引用。
• DocBook / DITA：企业级结构化出版能力强，也很重，除非你真有内容治理、复用和长周期出版需求，否则别轻易上。

如果你想 一份源文件生成多种格式，Pandoc AST 是一个很好的中间层。源头可以是 Markdown、AsciiDoc、HTML 或自定义 JSON，中间统一成 AST，再按目标输出 docx、PDF、HTML。需要注意：AST 能统一结构，不代表能统一所有版式细节。真正对版式敏感的部分，仍要落到模板、CSS、字体、分页规则和回归测试上。

汇总成一张表：

一句话：别先问“Markdown 行不行”，先问“谁是版式真相”。版式真相如果是 Word 模板，就围绕 docx 模板设计；如果是 Web 预览，就围绕 HTML/CSS 设计；如果是出版排版，就认真考虑 LaTeX 或 Typst。

10. 一份可复制的技术检查清单

如果你正在做类似系统，可以拿下面这张表自检。

总结：文档生成是一门小型工程学

从纯文本到 docx/pdf，表面是格式转换，里面是文档工程。

命令行工具能解决“能不能生成”。真正的产品要解决“生成得是否稳定、是否好看、是否安全、是否可维护”。这几个问题不解决，系统越多人用，越像一台会随机吐出惊喜的打印机。惊喜有时候是礼物，有时候是事故。

我的建议很朴素：

1. 不要默认源就是 Markdown，按目标选源格式。
2. 复杂场景把内容存成结构化 JSON，源/导出/预览各走各的链路。
3. 用模板和样式契约接管 docx。
4. 用明确渲染链路接管 PDF：Web 派、Word 派、出版派各有适用场景。
5. 学术、出版、复杂排版别躲 LaTeX；中文场景用 XeLaTeX/LuaLaTeX + CTeX。
6. Web 版本从异步导出、资源管理、安全沙箱开始设计。
7. 简历这类结构化文档，优先用 JSON/AST 做核心数据模型。
8. WYSIWYG 和多人协作晚一点再上，别第一天就把自己送进深水区。

最后一句话：转换工具是发动机，模板、校验、沙箱和回归测试才是刹车、方向盘和仪表盘。没有这些，跑得越快，越容易心慌。

扩展阅读

• Pandoc User's Guide
• Microsoft Learn: Word (.docx) Extensions to the Office Open XML File Format
• CommonMark Specification
• AsciiDoc Language Documentation
• reStructuredText Primer
• LaTeX Project
• Typst Documentation
• JSON Resume Schema

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。