如何在 Markdown 中写作，却以 Word 交付。高级架构师的工作流程

Source: Dev.to

冲突：工程 vs. 管理

企业 IT 中存在一个根本冲突：

• 工程师希望像写代码一样编写文档（Markdown，在 IDE 中，使用 Git 进行版本控制）。
• 管理层/客户希望“专业”的文档（Word，格式整齐，带有徽标）。

作为高级架构师，我拒绝在“深度工作”时间里与 Microsoft Word 的页边距或表格对齐争斗。但我也知道，直接把原始 .md 文件发给利益相关者显得不专业。

解决方案不是屈服于 Word，而是编译成 Word。

工具：带参考文档的 Pandoc

Pandoc 是一个命令行工具，用于转换文本格式。它在企业环境中的“杀手级特性”是 --reference-doc 参数，允许你将普通 Markdown 映射到严格格式化的企业 Word 模板。

工作流

教程：搭建文档工厂

步骤 1：安装 Pandoc

• macOS：

  brew install pandoc

• Windows：

  choco install pandoc

步骤 2：创建参考文档（模板）

1. 取一份公司已有的、格式良好的文档（包含正确的标题、字体和页脚徽标）。
2. 删除所有内容，只留下一个占位标题和一个段落。
3. 将其保存为 reference.docx。

步骤 3：使用 Markdown 编写

打开你的 IDE（VS Code、IntelliJ 等），使用标准 Markdown 编写规格说明。

# Architectural Decision Record 001

## Context
We need to migrate the Monolith to AWS.

## Decision
We will use AWS Lambda and Spring Boot SnapStart.

## Consequences
* Cost reduction by 40%
* Cold starts handled by SnapStart

步骤 4：构建命令

在终端运行以下简单命令：

pandoc input.md -o Final_Report.docx --reference-doc=reference.docx

刚才发生了什么？
Pandoc 将 input.md 中的文本“倾注”到 reference.docx 中定义的样式里。

• 你的 # Header 1 变成了公司官方的蓝色、16 号字体。
• 列表缩进完美。
• 公司徽标已经在页眉/页脚中。

为什么这是一项职业技巧

• 速度： 使用 Markdown 编写的速度约是 Word 的 3 倍。
• 版本控制： 在 Git 中跟踪更改。审阅二进制的 .docx 文件几乎不可能，但审阅 Markdown 却很直接；Word 文档作为构建产物生成。
• 专业性： 提交的文档外观完全符合业务期望，而无需打开 Office 365。

聪明工作，而非辛苦工作。让 CLI 来处理格式化。