企业官网建设流程全解析

做技术写作这些年，我最怕听到的一句话就是：“这段文档有点乱，你用 Word 帮我重新排一下版。”说这话的人往往觉得这不过是个“格式小问题”，但只有真正写过长期维护的技术文档、手册、白皮书的人才知道：Word 排版这件事，一旦混进了内容创作流程，它会像滚雪球一样越滚越大，最后把整个项目拖进“改一遍、崩一遍、校一遍、再崩一遍”的泥潭里。

没错，我这里的“抵制”，不是让你扔掉电脑去用纸笔，而是提倡一种观念上的转变：排版不该是技术文档的核心劳动，内容才是。与其把精力消耗在样式微调、目录刷新、页码错乱这些琐碎事上，不如从工作流层面根治问题——用一套轻量、自动化、可维护的文档生产流程，把排版从“人工手工作坊”变成“流水线自动输出”。这篇文章要聊的，就是我们在实际技术传播项目中完成的一次工作流改造：为什么做、怎么设计、踩了哪些坑，以及最终沉淀下来的可复用方案。

如果你正在被 Word 排版折磨，或者你的团队还在用“手工格式化”的方式维护一份几十页甚至上百页的技术文档，这篇文章里的经验可以直接拿过去用。

1. 为什么技术文档会被 Word 绑架

1.1 需求痛点：内容、样式、流转的三角博弈

先把话说透：Word 本身不是坏工具。它桌面上很好用，天然的所见即所得，任何人都能上手，随意拖拽、加粗、改颜色，很快就能得到一个“看起来差不多”的文档。但问题恰恰出在这个“看起来差不多”上——技术文档的复杂度，远超 Word 的舒适区。

技术文档不是一张传单，也不是一份三页的汇报。它的真实状态是：几十个章节、几十张图、几十个表格、几百条交叉引用、一堆版本号、一堆注意事项。你还得让人方便检索、方便更新、方便多人协作。一旦文档量级上来了，Word 排版的三大病根就开始发作：

第一，内容与格式高度耦合。你辛辛苦苦把标题字号调成三号黑体、正文调成小四宋体，结果领导说“换个风格看看”，你就得全选、重设、再修样式，运气不好还会把标题层级一起弄乱，改到一半发现目录引用全都失效了。第二，多人协作几乎是灾难。一份文档三个人改，改完合并时，格式错乱是家常便饭，轻则首行缩进丢失，重则整个样式表崩溃。第三，历史版本成为黑历史。每次更新都会诞生“最终版”“最终版2”“最终版-改”，因为文件是二进制封闭格式，没法做精细的 diff，你根本不知道同事在你出差时动过哪一段话。

这三者合起来，就形成了一个恶性循环：文档维护成本越来越高，更新频率越来越慢，内容准确性越来越差，最后文档变成了摆设，没人敢动它。

1.2 技术传播的视角：文档不是“一次交付”，而是“长期资产”

如果我们只站在“写一篇文档”的角度，这些问题顶多是“麻烦”。但站在技术传播（Technical Communication）的角度，问题就严重得多。技术文档本质上是一个产品，它有用户（工程师、客户、运维人员）、有迭代周期（每个版本都要同步更新）、有质量标准（准确、易读、可检索、风格一致）。

当你的文档处于“每次发布都要重新排版”的状态时，你就永远腾不出手来做真正有价值的事——比如优化信息架构、打磨语言表达、设计更清晰的图示、建立内容反馈机制。这些才是技术传播的核心价值，而手工排版恰恰是吞噬这些投入的黑洞。

所以，抵制 Word 排版，并不是抵制一个软件，而是抵制一种不可持续的工作方式。我们要做的，是把精力从“排格式”拉回到“写内容”和“设计信息”上。

2. 工作流改造的设计思路与方案选型

2.1 核心理念：内容与样式分离，格式交给脚本

我们最终确定的原则很简单：内容用纯文本写，样式用模板管，转换用脚本做。

这个理念其实不算新鲜，有点类似于前端开发里的“结构、样式、行为分离”。对应的技术选型就是：Markdown 写内容，CSS/Word 模板控制样式，Pandoc 做转换引擎。这套组合的好处是，写内容的人只需要关注文字本身，样式完全由模板统一决定，无论文档修改多少次，只要模板不变，输出样式就不会跑偏。

有人会问：为什么不用 AsciiDoc？因为它结构更严谨、更适合书籍类文档。说实话，AsciiDoc 确实很强大，也适合大型技术出版项目。但对于大多数技术团队和中小型文档场景来说，Markdown 的入门门槛更低、生态更广泛、和开发者的日常习惯更匹配。我们在项目里也见过一些用 AsciiDoc 用得非常好的团队，但那通常需要额外的学习成本。我们的目标是“让团队愿意用”，而不是“工具最完美”，所以选了 Markdown 作为折中方案。

也有人会问：直接用 LaTeX 不是更专业吗？LaTeX 排版质量确实顶尖，尤其学术文章、数学公式多的场景，它几乎无可替代。但它的学习曲线比较陡，而且对“普通工程师也要参与写文档”这个场景不太友好。我们团队里不是每个人都愿意学 LaTeX，而 Markdown 五分钟就能上手。还是那句话：工具要为工作流服务，而不是反过来。

2.2 工作流全景：从“打开 Word 手动排”到“一条命令出成品”

改造前的工作流是典型的手工模式：

用 Word 写内容 → 手动调整标题样式 → 手动插入页码、页眉页脚 → 手动生成目录 → 发给同事审阅 → 同事用 Word 修订 → 合并修订 → 重新调整被打乱的格式 → 再发下一轮……

这套流程最大的问题不是慢，而是每一步都依赖“人工精确操作”，而人工精确操作恰恰是最容易出错的环节。样式稍微失控，后面所有步骤都会跟着乱。

改造后的工作流变成了这样：

用 Markdown 写内容 → 提交到 Git 仓库 → 脚本自动构建 → 输出 Word、PDF、HTML 等多格式成品 → 团队成员直接在成品上审阅或继续在 Markdown 上改 → 改完再提交，脚本再构建……

这里的核心变化是：排版环节从“人工操作”变成了“自动化流水线”。内容从 Markdown 源文件到最终成品，中间不需要任何人碰 Word 编辑器，样式完全由模板统一接管。这样既保证了输出一致，也节省了大量重复劳动。

2.3 工具对比：Pandoc 之外的选项

先做个工具对比，给大家一个全景认识。我们评估过几类方案：

结论是明显的：对于“技术团队维护技术文档”这个场景，Markdown + Pandoc 是性价比最高的选择。它不要求你懂复杂的编程，只要你愿意把一个写文档的动作改成用文本编辑器，剩下的交给脚本。

3. 实操过程：搭建一套可复用的排版流水线

3.1 环境准备：装好这四样，就能开工

实操部分直接给干货。我们需要准备四样东西：

1. 一个文本编辑器：VS Code 或 Typora 都行，甚至 Vim 也可以，看个人喜好。关键是你要在纯文本环境里写内容，而不是在“富文本编辑器”里写。
2. Markdown 源文件：这是你的内容资产，以后所有维护工作都基于它。
3. Pandoc：格式转换引擎。它是整个工作流里最核心的齿轮，负责把 Markdown 转成 Word、HTML、PDF 等格式。安装很简单，官网下一个包，或者用包管理器：

   # macOS brew install pandoc # Ubuntu / Debian sudo apt-get install pandoc # Windows winget install JohnMacFarlane.Pandoc

4. Word 样式模板（reference.docx）：这是控制输出样式的关键文件。后面详细讲怎么制作。

装好之后，你的“排版生产力”就已经超越 90% 的手工 Word 用户了。

3.2 样式模板的制作：让 Word 的长相听你的话

Pandoc 的一大优势是，它可以把 Markdown 转成 Word，并且支持我们指定一个“参考模板”。这个模板决定了输出文档的字体、大小、标题样式、代码块样式、表格样式等。

最粗暴的方法有两种：

第一种，先去 GitHub 项目pandoc/goodies或者网上搜“reference.docx”，下载一份别人做好的模板，直接拿去用。好处是快，缺点是样式不一定适合你，改起来还得研究 Word 样式表。

第二种，自己做一个。其实不难：

# 先生成一个初始模板 pandoc -o custom-reference.docx --print-default-data-file reference.docx > custom-reference.docx # 或者用这条命令拿到默认模板 pandoc --print-default-data-file reference.docx > reference.docx

拿到reference.docx之后，用 Word 打开它。你会看到各种样式：Body Text、Heading 1、Heading 2、Title、Code Block 等。这时候只需要做一件事——改这些样式的字体、字号、行距、颜色，然后保存。这就是你的“模板定制”，不会写任何代码，完全靠 Word 的样式调整能力。

比如，我们项目里定义的是：标题一用 16pt 黑体，标题二用 14pt 黑体，正文用 10.5pt 宋体，行距 1.5 倍，代码块用等宽字体加浅灰底纹。这些设置只做一次，以后所有文档自动套用，再也不用每篇文章重调一遍。

3.3 核心命令：一条命令搞定多格式输出

这是整个工作流里最实用的部分。我用下面这条命令，完成 90% 的日常需求：

pandoc docs/用户手册.md \ --reference-doc=style/reference.docx \ --toc \ --toc-depth=2 \ -o dist/用户手册.docx

解释一下这条命令：

• --reference-doc=style/reference.docx：指定样式模板，输出 Word 会严格套用模板里的长相。
• --toc：自动生成目录，--toc-depth=2表示目录只显示两级标题，层级太多会把目录撑得很乱。
• -o dist/用户手册.docx：输出文件路径。

同样一份 Markdown，想出 HTML 版本也只需要换一下输出格式：

pandoc docs/用户手册.md \ --standalone \ --toc \ --toc-depth=2 \ --metadata title="用户手册" \ -o dist/用户手册.html

还有更常用的做法，是把转 HTML 和转 DOCX 合成一个命令，一条命令出两个格式：

pandoc docs/用户手册.md \ --reference-doc=style/reference.docx \ --toc \ --toc-depth=2 \ -o dist/用户手册.docx \ --standalone \ --metadata title="用户手册" \ -o dist/用户手册.html

实际项目里，我们还会用一个小脚本把这条命令封装起来，比如build.sh：

#!/bin/bash # 技术文档自动构建脚本 mkdir -p dist pandoc docs/用户手册.md \ --reference-doc=style/reference.docx \ --toc --toc-depth=2 \ -o dist/用户手册.docx pandoc docs/用户手册.md \ --standalone --toc --toc-depth=2 \ --metadata title="用户手册" \ -o dist/用户手册.html echo "构建完成，输出在 dist 目录"

之后每次文档有更新，只需要执行./build.sh，几秒钟就能拿到高质量的成品文档。

3.4 自动化扩展：让工作流跑得更远

做完了基本转换之后，我们在这个基础上还叠加了几层实用扩展，亲测有效，分享给大家。

第一层，接入 Git 做版本管理。这是对抗“最终版3”这类文件名混乱的最好武器。你只需要在 Markdown 目录里初始化一个 Git 仓库：

git init git add docs/ git commit -m "初版用户手册"

以后每次改动，先git diff看看改了什么，再提交。这个“看一眼改动内容”的动作，在 Word 时代几乎不可能做到，但在文本时代就是一条命令的事。

第二层，用 Makefile 或 CI 自动构建。如果团队有 CI 环境，还可以把build.sh挂到每次提交之后自动执行。代码提交了，文档自动构建，产出物自动发布到内部知识库。这样连手动执行命令的过程都省了。

第三层，配合文档站点生成器，比如 MkDocs、VitePress，把同样的 Markdown 源文件变成在线文档站。这样你就有了一份源文件，输出 Word 交付客户、输出 HTML 给内部翻、输出在线站点给用户查。内容一处维护，多端消费。

这三层做完，技术文档就和软件开发成了一个套路：有版本、有审查、有构建、有发布。文档不再是“写一次就丢的负担”，而是可以长期维护的沉淀资产。

3.5 多维输出：Pandoc 处理代码块、表格、图片的实战细节

写技术文档的人最关心的几个细节，这里一次性说透。

代码块。Pandoc 对 Markdown 里的围栏代码块支持很好，只要指定语言，输出的 Word 文档里就会自动带等宽字体和灰底：

​```python def hello(): print("Hello, world!") ​```

如果对默认代码块样式不满意，可以通过修改reference.docx里的Source Code样式来调整。建议统一用等宽字体，字号比正文小一档，再加浅灰色底纹。

表格。这是 Markdown 转 Word 的最大坑点。简单的表没问题，但列数多、行数多的时候，Word 默认的表格宽度处理非常别扭，常常挤成一团。我们的经验是：表格列数控制在五列以内，内容尽量精简，必要时拆分表格。Pandoc 内置的表格解析器能处理 pipe 表格，但宽度控制不强，想追求完美布局，就得在 reference.docx 里预先设计好“Table”样式，甚至直接用手动嵌入的 raw OpenXML 块。这块门槛稍高，普通场景下优先保证表格不溢出即可。

图片。Markdown 里引用图片用相对路径，Pandoc 会以源文件所在目录为基准解析。为了构建稳定，我们约定图片统一放到images/目录下，引用时写成：

![架构说明](./images/architecture.png)

这样不管是从仓库克隆到哪台机器，只要目录结构在，构建就不会断图。另外，图片的文件名不要用中文和空格，避免 Pandoc 在跨平台时把路径解析错。

4. 改造过程中的常见坑与避坑经验

4.1 常见问题速查表

做个表格，把实际项目中遇到的高频问题直接列出来：

这些坑我们基本都踩过一遍，最痛的就是第一个——中文排版。网上不少参考模板是英文环境做的，中文字体根本没有显式指定，结果生成出来的 Word “莫名变成了宋体”。后来我们用了一个小技巧：在 Word 模板里把“正文”“标题 1”“标题 2”这些关键样式的中文字体分别设置为黑体/宋体，西文字体设置为 Times New Roman，然后再也不用管了。

4.2 中文字体与细节：一次配好，一劳永逸

针对中文技术文档，有几个独有细节要注意。

第一个是字体嵌入问题。用 Pandoc 转 Word 时，它引用的是你模板里的字体名称，不代表客户打开时也能看到同款字体。如果客户机器没有这个字体，Word 会自动替换，版式就可能崩。所以对发给外部的文档，我们会额外做一步：将所有字体设置为 Windows 常见的宋体/黑体/微软雅黑，避免依赖稀缺字体。

第二个是首行缩进。中文正文习惯首行缩进两个字符，但这个习惯在英文排版里不存在。默认模板里 Body Text 样式一般没有首行缩进，需要手动在样式里设置：段落 → 特殊格式 → 首行缩进 → 2 字符。这是个很小但很影响观感的细节，没有设置的话，整篇文档看起来会像英文排版，非常别扭。

第三个是页面设置。技术文档通常需要注释、页眉、页脚。这些也可以在模板里预设好页边距、页眉文字、自动页码。设置一次后，无论文档多少页，页码都自动生成，彻底告别手动插页码然后一改就乱的问题。

4.3 团队协作中的习惯改造：最难的不是工具，是人

工具链搭起来之后，我们遇到的最大阻力来自团队习惯。几位老工程师习惯了直接用 Word 写文档，让他们改用 Markdown，他们第一反应是：“这啥，还得记语法？太麻烦了。”

我的经验是分三步走：

第一步，示范 + 见效。拿一份他们平常最痛苦的文档做演示，一键生成成品，和原来的 Word 版并列对比，让他们看到“的确省事”。第二步，降低门槛。不用大家学很多语法，只需要掌握#标题、-列表、普通文字，就足够覆盖 80% 的日常文档场景。顺手写一个简短的“团队写作指南”，五分钟看完。第三步，建立制度。文档统一进仓库，代码评审时顺便评审文档，不在 Word 里走审阅流程。一旦大家发现“在 Word 里改，改完脚本会覆盖”，自然就愿意切到 Markdown 上来改了。

其中一个很关键的技巧是，让大家先“复制-粘贴”老文档到 Markdown 里体验一把。很多人发现自己用 Markdown 写同样的内容，比 Word 排版快一倍还不止，这种正反馈比我们任何说教都管用。

5. 写在最后：工作流是长期投资

改造文档工作流这个事，短期看像“多了一道转换工序”，但长期看，它把我们从反复的格式劳作中解放了出来。我现在最深的体会是：排版本身不该是技术传播的瓶颈，真正该花时间的，是信息架构、语言表达和读者体验。

如果你现在正被一份几十页的 Word 文档折磨，不妨试一下这条思路：内容写成 Markdown，模板备好样式，脚本一键出文档。第一周可能有点不适应，第二周就会觉得回不去了。以后每次有人说“帮我用 Word 排一下版”，你就能底气十足地告诉他：文档源文件在仓库里，去那儿改，然后跑一下构建脚本，成品马上出来。

再分享一个小技巧收尾：我们每次发布新版本时，都会顺手把build.sh执行结果里的“耗时”打印出来——从 Markdown 到 Word 成品，全程不过两三秒。这个数字每次被同事看到，都是最好的广告。