如何将 Markdown 转换为 PDF

无论是在研发周会还是 SaaS 月度续约沟通，我越来越常听到“能不能发一份 PDF？”。开发团队习惯在仓库里审阅 Markdown，排版统一、版本可控，但走出工程圈，投资人、财务或合作伙伴还是把 PDF 看成可信交付物。与其在不同工具之间复制粘贴，不如搭建一条稳健的 Markdown→图像→PDF 流程，既保留文本语义，又能给对方熟悉的阅读体验。

1. 格式稳定：Markdown 渲染依赖阅读器，字体和段距经常失真。PDF 则把版式固化下来，外部审查就不会因为浏览器缩放错位。
2. 审计友好：合规或甲方评审通常要求带时间戳的 PDF。只要把生成的文件存入 Directus 或对象存储，就能追溯每次发布。
3. 跨团队沟通更顺滑：增长、销售、法务不会研究 Markdown 语法，他们只关心快速定位结论。加上页码和目录后，沟通成本立刻下降。
4. 可视化留痕：在 PDF 里嵌入的图表、注释、签批页能直接打印。Markdown 原稿可以作为附件保留，形成“所见即所得 + 原始文本”双轨档案。

• 把结构拆成若干“故事卡”，每张卡控制在 400-500 字，便于落在一页。
• 使用 ## 作为分页界标，### 控制页内层次，避免 PDF 阅读器自动拆分段落。
• 图片务必写清楚说明文字。打印版的读者看不到仓库里的上下文。
• 若要在 PDF 内保留链接，把链接文字写得更具描述性，例如“查看 SLA 附件”而不是“点击这里”。

我最终定下的流程来自 markdowntoimage.com：

1. 进入编辑器后粘贴单段 Markdown，选择 Deck 模板或自定义品牌色。模板中可以带 Logo、背景纹理、按钮色等设计细节。
2. 打开“Layout”面板，把文字行距设为 1.4 左右，正文宽度限定在 720px，既方便阅读又能确保导出的 PNG 不会被压缩得太狠。
3. 视需求在页脚添加 Sprint 名称、日期、页码或保密声明。记得用变量 {{page}} / {{pages}} 让标记自动计算。
4. 预览满意后导出 PNG。若一段内容超出画布，上方会提示，你可以将其切分成两张卡片。

• macOS：用 Preview 选中所有 PNG，拖到侧栏排序，点击“导出为 PDF”。
• Windows：把 PNG 选中后右键“打印”，选择 Microsoft Print to PDF，关掉页眉页脚即可。
• Linux / CI：利用 ImageMagick 的 convert *.png output.pdf，配合脚本自动化。注意在 CI 环境里要装 ghostscript，否则导出的文件可能偏大。
• 移动端紧急处理：在 iOS 的“文件” App 中全选图像，点三点菜单里的“制作 PDF”。虽然不适合大批量，但现场支持客户很方便。

生成 PDF 只是第一步，真正省心的是沉淀。

• 把最终 PDF 和对应的 Markdown 原文都上传到 Directus 的同一文件夹。命名里带上日期和迭代号，团队在搜索时可直接比对。
• 在 posts 集合里记录链接和版本号，配合 workflow 自动通知订阅者有新资料发布。
• 如果需要多语言内容，复制 post_translations 记录即可。不同语言共用同一套 PNG，只是替换文字内容，视觉保持一致。

1. 检查页码是否与目录一致，尤其是追加内容后容易错位。
2. 图片分辨率不要低于 2x，投屏或放大阅读时才不会模糊。
3. 关键数据点建议在正文中再写一次，避免图表导出失败时信息缺失。
4. 发布前在桌面和移动端各打开一次，确认字体没有意外替换。
5. 在 PDF 元数据里填写作者、关键词，方便后续检索。

我们曾在季度复盘中展示这个流程：

• 研发负责人仍用 Markdown 汇总本周完成、阻塞和下周计划。
• 技术写作用 Markdown2Image 模板在 15 分钟内生成 6 张主题页面。
• 运营在 Directus 里把 PDF 关联到“客户成功更新”集合，并触发邮件通知。
• 客户收到了仅 2MB 的 PDF，包含封面、页码、附录链接，还能回溯到原 Markdown。 结果是：之前复制到 PPT 再排版的 2 小时工作量，现在 30 分钟搞定，而且再也没人抱怨“格式乱了”。

Markdown 永远是书写和版本控制的首选，但把它转译成 PDF，意味着你主动为下游团队扫清了认知门槛。利用 Markdown2Image + PNG 合成 PDF 的方式，既保留了文本结构，又能精准呈现品牌体验。把这个流程固化到文档规范里，每一次对外分享都会更像一次精心准备的发布，而不是仓促导出的草稿。