make-pdf

用途

make-pdf 用于把任意 Markdown 文件转换成出版级质量的 PDF。它面向需要正式成品的场景：规范排版、封面、目录、页码、水印，而不是草稿式的临时产物。当用户提出“make a PDF”“export to PDF”“turn this markdown into a PDF”“generate a document”等请求时使用。它也支持语音触发别名，例如“make this a pdf”“export to pdf”“turn this into a pdf”“generate a pdf”“pdf this markdown”等。

主要能力

• 排版：1 英寸页边距、正文左对齐、全程 Helvetica、弯引号与破折号。
• 结构：智能分页、页码、封面页、页眉、可点击目录。
• 水印：可添加斜向 10% 不透明度的 DRAFT 水印，覆盖每一页。
• 复制质量：从 PDF 复制粘贴得到干净文字，不会出现“S a i l i n g”这类字符被拆散的情况。
• 图表：列 0 位置的 mermaid 或 excalidraw 围栏会渲染为清晰的矢量图，完全离线（内置打包，无 CDN）。缩进的围栏（位于列表内）按设计保持为普通代码块。损坏的围栏会显示带解析错误的红色诊断块，不会静默输出原始代码。
• 图片：本地图片自动内联（相对路径基于 Markdown 文件解析）。每张图片限制在内容框内，不会截断。过大的照片会降采样到打印分辨率（300dpi）。远程 http/https 图片默认被阻止并显示占位符，可用 --allow-network 获取。
• 其他格式：可输出单文件 HTML（内联 SVG 图表、data-URI 图片、零网络引用）或 Word 文档（保留标题、表格、代码，图表以 PNG 嵌入，布局由 Word 决定）。

使用方式

技能启动前会先运行 preamble 命令，读取回显的 KEY: value STATUS 行。若输出缺少 SKILL_START_PROTO: 1，则进入降级模式，采用安全默认值并提示用户运行 ./setup 或 /gstack-upgrade。

在使用任何 make-pdf 命令前，先运行 MAKE-PDF SETUP 检查二进制文件是否已构建。若打印 MAKE_PDF_NOT_AVAILABLE，需让用户从 gstack 仓库运行 ./setup 构建后重试。若打印 MAKE_PDF_READY，则 $P 为后续使用的二进制路径。

核心命令：

• "$P" generate <input.md> [output.pdf] — 将 Markdown 渲染为 PDF（80% 使用场景）
• "$P" generate --cover --toc essay.md out.pdf — 完整出版布局
• "$P" generate --watermark DRAFT memo.md draft.pdf — 斜向 DRAFT 水印
• "$P" preview <input.md> — 渲染 HTML 并在浏览器中打开（快速迭代）
• "$P" setup — 验证浏览器与 pdftotext 并运行冒烟测试
• "$P" --help — 完整参数参考

输出约定：stdout 成功时仅输出输出路径（一行）；stderr 输出进度（除非 --quiet）。退出码：0 成功 / 1 参数错误 / 2 渲染错误 / 3 目录页码失败 / 4 无可用浏览器。

常用模式：

• 备忘录/信件（80% 场景）："$P" generate letter.md，默认带页眉、页码和 CONFIDENTIAL 页脚。
• 出版模式："$P" generate --cover --toc --author "Garry Tan" --title "On Horizons" essay.md essay.pdf。每个顶层 H1 开始新页，可用 --no-chapter-breaks 禁用。
• 草稿水印："$P" generate --watermark DRAFT memo.md draft.pdf。
• 快速迭代："$P" preview essay.md，用相同打印 CSS 渲染 HTML 并在浏览器打开。
• 无品牌："$P" generate --no-confidential memo.md memo.pdf。
• 其他格式："$P" generate readme.md out.html --to html；"$P" generate readme.md out.docx --to docx。注意 --to 是输出格式，--format 是 --page-size 的别名，不要混淆。
• CI 模式："$P" generate docs.md --strict，缺失、远程、树外、超大和非普通文件的图片会以非零退出。

围栏信息字符串选项：mermaid title="Auth flow"（标题与 aria-label）、mermaid render=false（保持为代码块）、mermaid page=landscape（强制横向页）、mermaid page=portrait（否决自动横向）。

图片指令（写在图片之后）：{width=full}、{width=50%} 或 3in/8cm/200px、{page=landscape}、{page=portrait}。

适用场景

• 把 Markdown 备忘录、信件、文章导出为正式 PDF。
• 需要封面、目录、章节分页的出版级文档。
• 需要 DRAFT 水印的草稿阶段文档。
• 需要嵌入 mermaid 或 excalidraw 图表的文档。
• 需要单文件 HTML 或 Word 输出的场景。
• CI 流程中生成文档并严格校验资源。

限制

• 在 Linux 上需安装 fonts-liberation 以正确渲染（Helvetica 和 Arial 默认不存在，Liberation Sans 是标准度量兼容替代）。CI 和 Docker 构建通过 Dockerfile.ci 自动安装。
• Emoji 需要彩色 emoji 字体。macOS（Apple Color Emoji）和 Windows（Segoe UI Emoji）自带；多数 Linux 发行版和容器没有，emoji 会渲染为空框。./setup 会在 Linux 上尽力自动安装 fonts-noto-color-emoji。设置 GSTACK_SKIP_FONTS=1 可跳过安装。
• PDF 输出在 Aside 浏览器（macOS 15+，aside.com）运行时通过它打印，否则回退到 gstack 自带的无头浏览器。退出码 4 表示两者都不可用。--to html 和 --to docx 不需要浏览器（DOCX 中的图表需要浏览器栅格化，否则以源文本嵌入）。
• 远程图片默认被阻止，需 --allow-network。解析到 Markdown 目录之外的图片仍会内联但会警告，--strict 使其致命。超过 64MB 或非普通文件（fifo、设备）降级为占位符。
• 缩进的 mermaid/excalidraw 围栏保持为普通代码块。
• 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。