whitepaper

专业 PDF 生成器

此技能使用 pandoc 和 typst，将 Markdown 文件转换为排版专业的 PDF 白皮书。

资源

此技能包含以下内容（位于插件根目录中）：

• Typst 模板：templates/whitepaper.typ
• Source Sans 3 字体：fonts/ — 可变字体，支持所有字重（来自 Google Fonts 的开源字体）
• Source Code Pro 字体：fonts/（Regular、Bold、Italic、Bold Italic）— 用于代码块和行内代码

插件根目录： 插件根目录将动态确定（见下方步骤 2.5）

字体排印层级

元素	字重	样式
标题（H1）	Black（900）	大字号、紧凑字距
章节标题（H2）	Bold（700）	蓝色强调线
小标题（H3、H4）	Bold（700）	中等字号
正文	Regular（400）	两端对齐、行距舒适
代码	Source Code Pro	等宽

关键：完全自动执行

此技能完全无人值守运行。请勿：

• 在生成 PDF 前询问“要继续吗？”
• 在清理前询问“要删除这些文件吗？”
• 在任何步骤询问“这样可以吗？”
• 在步骤之间等待用户确认
• 暂停以展示中间结果
• 请求文件操作权限

必须执行的操作：

• 按顺序执行所有步骤，不得停止
• 调用后立即生成 PDF
• 创建 PDF 后立即删除所有源文件
• 一切完成后再与用户沟通
• 报告最终结果：“PDF 已创建：[path]”

如果你准备在 PDF 生成或清理期间向用户提问，请立即停止提问，直接执行操作。

用法

用户要求创建 PDF 时，请按以下步骤操作：

1. 确定输入和输出

• 解析 $ARGUMENTS，获取输入 Markdown 文件以及可选的输出 PDF 路径
• 如果未提供输出路径，则使用与输入文件同名且扩展名为 .pdf 的路径
• 如果未提供输入文件，则询问用户要转换哪个 Markdown 文件
• 检查文件的 YAML frontmatter（见下方“Frontmatter 参考”）。如果缺少 title，则在继续前询问用户标题。如果缺少 date，则默认为今天的日期。

2. 安装依赖（如缺失）

对每个缺失的工具运行以下命令 — 脚本会自动检测平台：

OS=$(uname -s)
# pandoc
command -v pandoc >/dev/null 2>&1 || {
  [ "$OS" = "Darwin" ] && brew install pandoc || sudo apt-get update && sudo apt-get install -y pandoc
}
# typst
command -v typst >/dev/null 2>&1 || {
  [ "$OS" = "Darwin" ] && brew install typst || {
    curl -fsSL https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-musl.tar.xz \
      | tar xJ --strip-components=1 -C /usr/local/bin/ typst-x86_64-unknown-linux-musl/typst
    chmod +x /usr/local/bin/typst
  }
}

2.5 定位插件根目录

关键：复制资源前，必须确定插件根目录。

插件根目录包含 templates/ 和 fonts/ 目录。使用以下单条命令：

PLUGIN_ROOT=$([ -d ".claude/plugins/project-management" ] && echo ".claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT")
echo "Using plugin root: $PLUGIN_ROOT"
ls "$PLUGIN_ROOT/templates/whitepaper.typ" || echo "ERROR: Template not found!"

预期位置： .claude/plugins/project-management

3. 将模板复制到输出目录

将 typst 模板复制到与输出 PDF 相同的目录：

PLUGIN_ROOT=$([ -d ".claude/plugins/project-management" ] && echo ".claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT")
cp "$PLUGIN_ROOT/templates/whitepaper.typ" <output-directory>/whitepaper.typ

将 <output-directory> 替换为生成 PDF 的目录（例如 project-guides/）。

4. 运行 Pandoc

使用以下确切标志执行转换。从输出目录运行，以便找到模板：

cd <output-directory> && \
PLUGIN_ROOT=$(if [ -d "../.claude/plugins/project-management" ]; then echo "../.claude/plugins/project-management"; elif [ -d ".claude/plugins/project-management" ]; then echo ".claude/plugins/project-management"; else echo "$CLAUDE_PLUGIN_ROOT"; fi) && \
TYPST_FONT_PATHS="$PLUGIN_ROOT/fonts" pandoc <input.md> \
  -o <output.pdf> \
  --pdf-engine=typst \
  -V template="whitepaper.typ" \
  -V mainfont="Source Sans 3" \
  -V fontsize=10pt \
  -V papersize=a4

project-guides/ADMIN-GUIDE.md 的示例：

cd content && \
PLUGIN_ROOT=$([ -d "../.claude/plugins/project-management" ] && echo "../.claude/plugins/project-management" || echo "$CLAUDE_PLUGIN_ROOT") && \
TYPST_FONT_PATHS="$PLUGIN_ROOT/fonts" pandoc ADMIN-GUIDE.md -o ADMIN-GUIDE.pdf --pdf-engine=typst -V template="whitepaper.typ" -V mainfont="Source Sans 3" -V fontsize=10pt -V papersize=a4

注意：不要传递 --toc — 模板会生成带有适当样式的目录页。

5. 清理（必须执行 — 不得跳过）

关键：必须在生成 PDF 后立即执行清理。最后只能保留 PDF。

# Remove ALL intermediate files in one command
rm -f <output-directory>/whitepaper.typ <input.md> <input-without-extension>.plain.html <input-without-extension>.html

清理 project-guides/AUTHOR-GUIDE.md 的示例：

rm -f project-guides/whitepaper.typ project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.plain.html project-guides/AUTHOR-GUIDE.html

清理后，只应存在 project-guides/AUTHOR-GUIDE.pdf。不得存在 .md、.html 或 .plain.html 文件。

6. 报告结果

"PDF created: [output.pdf]"

Frontmatter 参考

模板会读取 Markdown 文件中的 pandoc YAML frontmatter，用于填充标题页和页脚。Frontmatter 块必须位于文件最开头，并由 --- 行分隔。

必需字段

字段	用途	示例
title	封面标题、PDF 元数据	"AEM Code Sync for Edge Delivery Services"

推荐字段

字段	用途	示例
subtitle	封面上强调线下方的第二行文字	"Technical Architecture and Security Documentation"
date	封面和页脚	"January 29, 2026"

可选字段

字段	用途	示例
author	封面上的作者列表	请参见下方的结构化示例

最简示例

---
title: "AEM Code Sync for Edge Delivery Services"
subtitle: "Technical Architecture and Security Documentation"
date: "January 29, 2026"
---

包含作者的完整示例

---
title: "AEM Code Sync for Edge Delivery Services"
subtitle: "Technical Architecture and Security Documentation"
date: "January 29, 2026"
author:
  - name: "Jane Smith"
    affiliation: "Edge Delivery Services"
  - name: "John Doe"
    affiliation: "Security Engineering"
---

模板的渲染效果

• 标题：封面上的大号黑色粗体文字
• 副标题：强调分隔线下方较浅的文字
• 日期：显示在封面和页脚
• 作者：显示在封面上，可选附带所属机构

常见错误

• 将 frontmatter 放在标题或空行之后（它必须是文件的第一项内容）
• 使用包含冒号的未加引号字符串，例如 title: AEM: A Guide——请用引号括起来
• 在 frontmatter 中添加 fontsize 或 papersize 等 pandoc 变量——请改为将其作为 -V 标志传递给 pandoc（该技能会自动处理）

模板设计

该模板提供专业的文档格式：

• 使用 Source Sans 3 实现专业排版（来自 Google Fonts 的开源字体）
• 使用蓝色强调色（#0066cc）显示章节分隔线和链接
• 简洁的页眉，包含标题/副标题（无分隔线）
• 页脚，包含日期和页码（标题页上隐藏）
• 使用 Source Code Pro 显示代码块和行内代码
• 自动生成目录页面
• 标题页带有强调分隔线

模板功能

功能	描述
标题页	简洁设计，包含标题、副标题、日期和作者
目录	在第 2 页自动生成
H1 标题	黑色粗体，前置分页符
H2 标题	粗体，带蓝色强调线
代码块	灰色背景、圆角
引用块	蓝色左边框、浅蓝色背景
表格	浅色边框、粗体表头行
链接	蓝色（#0066cc）

自定义文档

用户可以使用 -V key=value 覆盖 pandoc 变量：

变量	默认值	描述
papersize	a4	页面大小（a4、us-letter 等）
fontsize	10pt	正文字号
template	whitepaper.typ	Typst 模板文件
mainfont	Source Sans 3	正文字体

要求

• 必须安装 pandoc 和 typst（若未安装，该技能会自动安装）
  • macOS：通过 Homebrew（brew）
  • Linux：通过 apt-get 安装 pandoc，通过 GitHub release 二进制文件安装 typst
• 插件的 fonts/ 目录中包含 Source Sans 3 字体

故障排除

如果 typst 找不到字体，请确保已正确设置 TYPST_FONT_PATHS 环境变量：

export TYPST_FONT_PATHS=${CLAUDE_PLUGIN_ROOT}/fonts

问题	解决方案
找不到字体	检查 TYPST_FONT_PATHS 是否指向插件的 fonts/ 目录
找不到模板	确保已将 whitepaper.typ 复制到输出目录
表格未分页	模板会自动处理
缺少标题页	检查 frontmatter 是否包含 title 字段