狸想岛 · AI 实战学习社区

🎯 学 gstack 的 Markdown 到 PDF 的转换系统：把部署报告、审查仪表盘、设计文档等 Markdown 内容一键转为美观的 PDF——适合分享给非技术人员、归档备查或满足合规要求。 ⏱️ 预计时间：15 分钟

[!tip] 初学提示：如果你不熟悉 CI/CD 概念，可以先理解"自动化 PDF 生成流程"部分的实际用途——它能帮你省去大量手动导出文档的时间。

[!quote]- 📖 原Skill精要 技能名称：make-pdf 核心功能：将任意 Markdown 文件转为出版级质量 PDF。标准 1 英寸页边距、智能分页、页码、封面页、页眉、弯引号和长破折号、可点击目录、对角 DRAFT 水印。不是草稿产物——是成品。适合分享给非技术人员、归档备查或满足合规要求。 所属体系：gstack 虚拟工程团队 协作关系：可将 [[L6-18-审查仪表盘|审查仪表盘]]、[[L6-36-项目复盘大师|retro]] 等产出的 Markdown 文档一键转为 PDF

§1 课程概览

[!info] 白话小课堂 一句话：你写的 Markdown 文档（设计系统、审查报告、部署记录），一键变成带封面、目录、页码、品牌水印的专业 PDF——不用打开 Word 排版，不用手动导出。

为什么重要：Markdown 是工程师的通用语言，但不是所有读者都熟悉 Markdown。你的设计文档需要发给外部设计顾问（他们只用 PDF），你的审计报告需要归档（合规要求 PDF 不可篡改），你的商家入驻指南需要给商户下载（他们不懂 Markdown）。make-pdf 桥接了"工程师友好的编写格式"和"非工程师友好的交付格式"。

核心心法：静态快照的价值。PDF 不是"实时数据的最佳格式"，但它是"在某个时间点确认了什么的不可变记录"——合规归档需要的就是这种不可变性。生成时机要在 CI/CD 里自动化，避免"人记得要导出"的依赖。

§2 结构拆解

核心特征

管理对象：Markdown 文档 → 出版级 PDF 的转换管线
核心原则：成品非草稿 —— 输出的是可以直接交付的出版级 PDF
关键设计：
- 三场景适配：对外分享（品牌水印 + 公司 logo）、合规归档（审计编号 + 不可篡改）、客户交付（清晰步骤 + 代码示例）
- CI/CD 自动化：内容源（Markdown 在 git 中）更新 → 自动触发 PDF 生成 → 上传 CDN
- 版本可追溯：PDF 封面页/页眉/文件名均含版本号
- 中英文混排：CJK 字体回退链 + 等宽字体中文宽度处理

通用结构

输入层： → Markdown 源文件（标题、表格、代码块、callout） → 渲染参数（--title、--header-logo、--footer、--output） → 场景上下文（对外分享 / 合规归档 / 客户交付） ├── 格式引擎 │ ├── 页边距与分页（智能分页，避免跨页断行） │ ├── 封面页生成（标题、版本号、日期、logo） │ ├── 目录生成（可点击跳转） │ └── 页眉页脚（logo、页码、版权信息） ├── 内容渲染 │ ├── Markdown → 排版（标题层级、表格、代码块） │ ├── 代码块等宽字体保留 │ ├── 中英文混排（CJK 字体回退链） │ └── 图片嵌入（截图、示意图） ├── 水印与签名 │ ├── DRAFT 水印（对角斜排） │ └── 版本号嵌入 └── 输出层 └── PDF 文件（含元数据：标题、作者、版本）

§3 make-pdf 的使用场景

什么内容应该转 PDF？

对外分享

→ 设计系统文档（DESIGN.md）→ 分享给外部设计顾问 → 审查报告 → 给不熟悉 Markdown 的管理层 → Retro 报告 → 归档到项目文档

合规归档

→ 安全审计报告（/cso 输出） → 部署记录（/land-and-deploy Deploy Reports） → 代码冻结记录（/freeze 审计日志）

客户交付

→ API 文档（OpenAPI spec 转 PDF） → 用户手册 → 发布说明（CHANGELOG → Release Notes PDF）

渲染特性

→ 保留 Markdown 格式（标题、表格、代码块、callout） → 可自定义页眉/页脚（公司 logo、页码） → 可自定义字体和颜色 → 支持中英文混排

§4 电商 Skill 案例：电商平台API文档自动生成与多格式输出

🛒 实战案例：某电商SaaS开放平台维护200+ API端点，OpenAPI spec(openapi.yaml)是客户端SDK自动生成的输入源。对外交付物包括——开发者门户的在线API文档(Markdown→HTML)、客户集成的PDF参考手册(Markdown→PDF)、内部wiki的架构文档(Markdown→Markdown交叉链接)。三大类文档的源都是Markdown文件——使用/make-pdf将Markdown自动转换为出版级PDF。

API参考手册生成：/make-pdf docs/api-reference.md --title "Mega Shop API Reference v2.5.0" --header-logo "assets/logo.png" --footer "Mega Shop API v2.5.0 | © 2026" --output "api-reference-v2.5.0.pdf"→生成187页PDF。内容包含——API概览、认证说明(OAuth2.0流程)、200+端点详细定义(路径/参数/请求体/响应schema/错误码/示例请求)、SDK快速入门(iOS/Android/Web)、变更日志(breaking changes标注)。特殊处理——代码块等宽字体(API请求示例保持缩进和换行)、响应schema的JSON代码块自动格式化、表格智能分页(避免跨页断行导致表头丢失)、图片嵌入(架构图/认证流程图)。

API变更同步检测：/make-pdf运行前自动执行git diff origin/main...HEAD -- docs/api-reference.md→如果有变更→在PDF封面页页脚添加版本水印"DRAFT - Generated from commit a1b2c3d"→标记为草稿版本，正式版本通过--final标志取消水印。版本可追溯性——PDF元数据中嵌入源commit SHA，用户可以从PDF元数据追溯到生成的Git版本。

CI/CD自动生成：在CI pipeline中添加步骤——内容有变更时自动运行/make-pdf→生成最新PDF→上传到CDN(https://docs.mega-shop.com/api-reference-v2.5.0.pdf)→自动替换旧版本链接。如果/make-pdf失败（如Markdown语法错误导致PDF生成中断）→阻断CI并报告错误行号。版本对应——平台v2.5.0对应API参考手册v2.5.0（内容共享同一版本号，用户看到的PDF永远匹配当前平台版本）。

🔑 启示：make-pdf解决的是"Markdown vs PDF"的工程实践鸿沟。Markdown适合版本控制和协作（git diff友好），但客户需要PDF（格式固定、能打印、能签名归档）。关键设计——源文件在git中（Markdown可审查可追溯），PDF在CI中自动生成（确保PDF与源文件同步），版本号对应（PDF版本号=平台版本号）。这确保了"客户看到的PDF"和"开发者维护的Markdown"永远不会漂移。

[!info] 参考来源 Markdown-to-PDF 转换参考了 Pandoc 和 md-to-pdf 的转换模式。API文档版本管理参考了 OpenAPI Generator 项目的 spec-to-docs 自动生成流程。

§5 掌握检验

Q1：make-pdf 的核心功能是什么？

A) 将 PDF 转换为 Markdown
B) 将 Markdown 文件转换为出版级质量的 PDF（含标准页边距、智能分页、页码、封面页、可点击目录）
C) 在线编辑 PDF 文件
D) 将 Word 文档转换为 Markdown

Q2：以下哪种内容不适合通过 make-pdf 转换为 PDF？

A) 安全审计报告（/cso 输出）——需要合规归档
B) 设计系统文档（DESIGN.md）——需要分享给外部设计顾问
C) 实时数据仪表盘——内容每分钟都在变化，PDF 生成后立即过时
D) API 文档——需要客户交付

Q3：make-pdf 的三种使用场景（对外分享、合规归档、客户交付）各有什么不同的需求？请从"格式要求"、"更新频率"和"读者身份"三个角度对比。为什么同一个 Markdown 文件在这些不同场景下可能需要不同的 PDF 渲染参数（如是否加水印、是否含目录、页眉页脚内容）？

Q4：电商案例中将 Markdown 商家入驻指南转为 PDF——为什么这个流程被设计为"CI/CD 中自动生成"而非"手动导出一次就够"？如果商家指南的内容每两周更新一次（如结算规则变动、API 端点变更），手动导出的流程会导致什么问题？

Q5：make-pdf 生成了 PDF，版本号为 v2.3.0。但用户下载 PDF 后不知道这个 PDF 对应的是哪个版本的平台。如何确保 PDF 的"版本可追溯性"——用户看到 PDF 中的内容后，如何确认这些内容对应的是当前正在使用的平台版本？如果用户在平台升级到 v2.4.0 后仍然使用 v2.3.0 的 PDF 指南，可能遇到什么具体问题？

Q6：make-pdf 支持中英文混排。中英文混排的 PDF 生成中常见的格式问题有哪些（如中英文字体回退、标点符号间距、代码块中的中文字符）？如果生成的 PDF 中代码块（等宽字体）包含了中文字符，为什么可能出现"对齐错乱"——等宽字体的"等宽"是对英文字符而言的，中文字符的宽度如何处理？

§6 答案

点击查看答案

Q1：B —— make-pdf 将任意 Markdown 文件转换为出版级质量 PDF。

Q2：C —— 实时数据仪表盘不适合转 PDF，因为 PDF 是静态快照——生成的那一刻数据就开始过时。

Q3：对外分享——格式要求：专业排版（有公司 logo、品牌色）、更新频率：每次设计系统更新时重新生成、读者身份：外部设计顾问（不熟悉项目内部术语，需要更多解释性内容）。合规归档——格式要求：标准的审计格式（页眉含审计编号、页脚含页码和总页数）、更新频率：固定（审计完成后不再更新）、读者身份：审计师/合规官（关注完整性和不可篡改性）。客户交付——格式要求：清晰的操作指南风格（步骤编号、截图清晰）、更新频率：每次 API 版本更新时、读者身份：客户的开发人员（需要准确的代码示例和 API 参数说明）。不同渲染参数：DRAFT 水印——合规归档用（表明"审计草稿未最终确认"），对外分享不用。目录——客户交付需要（长文档导航），合规归档可能不需要（审计师按章节编号查找而非目录）。

Q4：内容源（Markdown）在 git 中持续更新——结算规则变了、API 端点改了、上架流程增加了新步骤。手动导出 = 内容更新了但 PDF 还是旧版本 = 商家看到的指南与实际平台不同 = 商家按指南操作但找不到按钮/API 返回错误/结算金额不对 → 商家投诉 → 客服团队无法判断是"商家操作错误"还是"指南过时"。CI/CD 自动生成：Markdown 内容更新 → git commit → CI 触发 → 自动生成 PDF → 上传到 CDN → 商家后台"下载指南"链接自动指向最新版本。手动流程的漂移风险：内容更新和 PDF 更新之间存在"人记得要导出"的依赖——总会有人忘记。

Q5：版本可追溯性设计：①PDF 封面页包含版本号（"v2.3.0"）和生成日期；②页眉包含版本号（每个页面都有——即使封面被撕掉也能知道版本）；③PDF 文件名包含版本号（merchant-guide-v2.3.0.pdf）；④在 PDF 第一页添加版本兼容性声明（"本指南适用于 Mega Shop 平台 v2.3.0 及以上版本"）。用户使用过时 PDF 的问题：API 端点从 /v1/products 改为 /v2/products → PDF 中的代码示例返回 404；结算规则从"T+7"改为"T+3" → 商家以为要等 7 天实际上 3 天到账；上架流程增加了"成分检测报告上传"步骤 → PDF 中没有这个步骤 → 商家提交的商品被驳回。

Q6：常见格式问题：①中英文字体回退——PDF 渲染引擎使用英文字体（如 Inter）渲染中文 → 中文字符显示为方块（tofu）→ 需要配置 CJK 字体回退链（Inter → Noto Sans CJK）。②标点符号间距——英文句号后加空格（"Hello. World"），中文句号后不加空格（"你好。世界"）。中英混排时渲染引擎可能在中文句号后也加空格 → 破坏中文排版习惯。③代码块中的中文字符——等宽字体的"等宽"是对拉丁字符（a-z, 0-9）而言的——一个中文字符通常是 2 个英文字符宽度。但不同等宽字体对中文宽度的处理不一致（有的用 2em，有的用单独的 CJK 宽度）→ 中英文混排的代码块中对齐容易错乱（如 ASCII 表格中的中文列头会导致列宽计算错误）。解决方案：代码块只用英文（中文注释放在代码块外的段落中），或在代码块中使用专门为 CJK 设计的等宽字体（如 Sarasa Gothic）。

（5/6 通过）

L6-44：文档生成器 —— 把Markdown一键转成精美PDF