Back to Details

whitepaper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Professional PDF Generator

专业PDF生成工具

This skill converts Markdown files into professionally typeset PDF whitepapers using pandoc and typst.
本Skill使用pandoc和typst将Markdown文件转换为排版专业的PDF白皮书。

Assets

资源

The skill includes (located in the plugin's root directory):
  • Typst template: 
    templates/whitepaper.typ
  • Source Sans 3 fonts: 
    fonts/
    — variable fonts supporting all weights (open source from Google Fonts)
  • Source Code Pro fonts: 
    fonts/
    (Regular, Bold, Italic, Bold Italic) — used for code blocks and inline code
Plugin Root: The plugin root is determined dynamically (see Step 2.5 below)
本Skill包含以下内容（位于插件根目录）：
  • Typst模板：
    templates/whitepaper.typ
  • Source Sans 3字体：
    fonts/
    —— 支持全字重的可变字体（来自Google Fonts的开源字体）
  • Source Code Pro字体：
    fonts/
    （常规、粗体、斜体、粗斜体）—— 用于代码块和行内代码
插件根目录：插件根目录会动态确定（见下文第2.5步）

Typography Hierarchy

排版层级

ElementWeightStyle
Headlines (H1)Black (900)Large, tight tracking
Section headlines (H2)Bold (700)Blue accent line
Subheads (H3, H4)Bold (700)Medium size
Body copyRegular (400)Justified, comfortable leading
CodeSource Code ProMonospace
元素字重样式
主标题（H1）Black（900）大字号，紧凑字距
章节标题（H2）Bold（700）蓝色装饰线
子标题（H3、H4）Bold（700）中等字号
正文Regular（400）两端对齐，舒适行高
代码Source Code Pro等宽字体

CRITICAL: FULLY AUTOMATIC EXECUTION

重要说明：完全自动执行

THIS SKILL RUNS COMPLETELY UNATTENDED. DO NOT:
  • Ask "Should I proceed?" before generating PDF
  • Ask "Should I delete these files?" before cleanup
  • Ask "Is this okay?" at any step
  • Wait for user confirmation between steps
  • Pause to show intermediate results
  • Request permission for file operations
REQUIRED BEHAVIOR:
  • Execute all steps sequentially without stopping
  • Generate PDF immediately when invoked
  • Delete ALL source files immediately after PDF is created
  • Only communicate with user AFTER everything is complete
  • Report final result: "PDF created: [path]"
If you find yourself about to ask the user a question during PDF generation or cleanup, STOP and just execute the operation instead.
本Skill完全自动运行。请勿：
  • 生成PDF前询问“是否继续？”
  • 清理前询问“是否删除这些文件？”
  • 在任何步骤询问“这样可以吗？”
  • 在步骤之间等待用户确认
  • 暂停以展示中间结果
  • 请求文件操作权限
必须遵循的行为：
  • 按顺序执行所有步骤，无需停顿
  • 调用后立即生成PDF
  • PDF生成完成后立即删除所有源文件
  • 仅在所有操作完成后与用户沟通
  • 报告最终结果："PDF已创建：[路径]"
如果在PDF生成或清理过程中你想要向用户提问，请停止提问并直接执行操作。

Usage

使用方法

When the user asks to create a PDF, follow these steps:
当用户要求创建PDF时，请遵循以下步骤：

1. Determine Input and Output

1. 确定输入与输出

  • Parse 
    $ARGUMENTS
    for the input markdown file and optional output PDF path
  • If no output path is given, use the same name as the input with a 
    .pdf
    extension
  • If no input is given, ask the user which markdown file to convert
  • Check the file's YAML frontmatter (see "Frontmatter Reference" below). If 
    title
    is missing, ask the user for a title before proceeding. If 
    date
    is missing, default to today's date.
  • 解析
    $ARGUMENTS
    获取输入Markdown文件和可选的输出PDF路径
  • 如果未指定输出路径，使用与输入文件同名的
    .pdf
    文件
  • 如果未指定输入文件，询问用户要转换哪个Markdown文件
  • 检查文件的YAML前置内容（见下文“前置内容参考”）。如果缺少
    title
    字段，在继续前询问用户标题。如果缺少
    date
    字段，默认使用当前日期。

2. Install Dependencies (if missing)

2. 安装依赖（如果缺失）

Run for each missing tool — the script auto-detects the platform:
bash
OS=$(uname -s)
为每个缺失的工具运行以下命令——脚本会自动检测平台：
bash
OS=$(uname -s)

pandoc

pandoc

command -v pandoc >/dev/null 2>&1 || { [ "$OS" = "Darwin" ] && brew install pandoc || sudo apt-get update && sudo apt-get install -y pandoc }
command -v pandoc >/dev/null 2>&1 || { [ "$OS" = "Darwin" ] && brew install pandoc || sudo apt-get update && sudo apt-get install -y pandoc }

typst

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 } }
undefined
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 } }
undefined

2.5 Locate Plugin Root Directory

2.5 定位插件根目录

CRITICAL: Determine the plugin root before copying assets.
The plugin root contains 
templates/
and 
fonts/
directories. Use this single command:
bash
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!"
Expected location: 
.claude/plugins/project-management
重要说明：复制资源前必须确定插件根目录。
插件根目录包含
templates/
和
fonts/
目录。使用以下命令：
bash
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. Copy Template to Output Directory

3. 复制模板到输出目录

Copy the typst template to the same directory as the output PDF:
bash
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
Replace 
<output-directory>
with the directory where the PDF will be generated (e.g., 
project-guides/
).
将typst模板复制到输出PDF所在的目录：
bash
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. Run Pandoc

4. 运行Pandoc

Execute the conversion with these exact flags. Run from the output directory so the template is found:
bash
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
Example for 
project-guides/ADMIN-GUIDE.md
:
bash
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
Note: Do not pass 
--toc
— the template generates its own table of contents page with proper styling.
使用以下精确参数执行转换。从输出目录运行以确保能找到模板：
bash
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
的示例：
bash
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. Clean Up (MANDATORY - DO NOT SKIP)

5. 清理（必须执行 - 请勿跳过）

CRITICAL: You MUST execute cleanup immediately after PDF generation. Only PDF should remain.
bash
undefined
重要说明：PDF生成完成后必须立即执行清理。仅保留PDF文件。
bash
undefined

Remove ALL intermediate files in one command

一条命令删除所有中间文件

rm -f <output-directory>/whitepaper.typ <input.md> <input-without-extension>.plain.html <input-without-extension>.html

**Example cleanup for `project-guides/AUTHOR-GUIDE.md`:**
```bash
rm -f project-guides/whitepaper.typ project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.plain.html project-guides/AUTHOR-GUIDE.html
After cleanup, only 
project-guides/AUTHOR-GUIDE.pdf
should exist. No .md, .html, or .plain.html files.
rm -f <output-directory>/whitepaper.typ <input.md> <input-without-extension>.plain.html <input-without-extension>.html

**针对`project-guides/AUTHOR-GUIDE.md`的清理示例：**
```bash
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. Report Result

6. 报告结果

"PDF created: [output.pdf]"
"PDF已创建：[output.pdf]"

Frontmatter Reference

前置内容参考

The template reads pandoc YAML frontmatter from the markdown file to populate the title page and footer. The frontmatter block must be the very first thing in the file, delimited by 
---
lines.
模板会从Markdown文件中读取pandoc YAML前置内容，用于填充标题页和页脚。前置内容块必须是文件的第一部分，用
---
行分隔。

Required Fields

必填字段

FieldPurposeExample
title
Cover page headline, PDF metadata
"AEM Code Sync for Edge Delivery Services"
字段用途示例
title
封面标题，PDF元数据
"AEM Code Sync for Edge Delivery Services"

Recommended Fields

推荐字段

FieldPurposeExample
subtitle
Second line on cover, below the accent line
"Technical Architecture and Security Documentation"
date
Cover page and page footer
"January 29, 2026"
字段用途示例
subtitle
封面第二行，位于装饰线下方
"Technical Architecture and Security Documentation"
date
封面和页脚显示
"January 29, 2026"

Optional Fields

可选字段

FieldPurposeExample
author
Author list on cover pageSee structured example below
字段用途示例
author
封面作者列表见下方结构化示例

Minimal Example

最简示例

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

Full Example with Authors

包含作者的完整示例

yaml
---
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"
---
yaml
---
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"
---

What the Template Renders

模板渲染内容

  • Title: Large black-weight text on the cover
  • Subtitle: Lighter text below the accent divider line
  • Date: Shown on the cover and in the page footer
  • Authors: Listed on the cover with optional affiliation
  • 标题：封面的大字号黑粗体文本
  • 副标题：装饰分隔线下方的浅色文本
  • 日期：显示在封面和页脚
  • 作者：在封面列出，可包含所属机构

Common Mistakes

常见错误

  • Putting the frontmatter after a heading or blank line (it must be the first thing in the file)
  • Using unquoted strings that contain colons, e.g. 
    title: AEM: A Guide
    -- wrap in quotes
  • Adding pandoc variables like 
    fontsize
    or 
    papersize
    in the frontmatter -- pass those as 
    -V
    flags to pandoc instead (the skill handles this automatically)
  • 将前置内容放在标题或空行之后（必须是文件的第一部分）
  • 使用包含冒号的未加引号字符串，例如
    title: AEM: A Guide
    —— 需用引号包裹
  • 在前置内容中添加
    fontsize
    或
    papersize
    等pandoc变量 —— 应作为
    -V
    参数传递给pandoc（本Skill会自动处理）

Template Design

模板设计

The template provides professional document formatting:
  • Professional typography using Source Sans 3 (open source font from Google Fonts)
  • Blue accent color (#0066cc) for section dividers and links
  • Clean header with title/subtitle (no separator line)
  • Footer with date and page numbering (hidden on title page)
  • Source Code Pro for code blocks and inline code
  • Automatic table of contents page
  • Title page with accent divider line
模板提供专业的文档格式：
  • 专业排版：使用Source Sans 3（来自Google Fonts的开源字体）
  • 蓝色装饰色（#0066cc）：用于章节分隔线和链接
  • 简洁页眉：包含标题/副标题（无分隔线）
  • 页脚：包含日期和页码（标题页隐藏）
  • Source Code Pro：用于代码块和行内代码
  • 自动生成目录页
  • 带装饰分隔线的标题页

Template Features

模板特性

FeatureDescription
Title pageClean design with title, subtitle, date, authors
Table of contentsAuto-generated on page 2
H1 headingsBlack weight, page break before
H2 headingsBold with blue accent line
Code blocksGray background, rounded corners
BlockquotesBlue left border, light blue background
TablesLight borders, bold header row
LinksBlue color (#0066cc)
特性描述
标题页简洁设计，包含标题、副标题、日期、作者
目录自动生成在第2页
H1标题黑粗体，前分页
H2标题粗体加蓝色装饰线
代码块灰色背景，圆角
引用块蓝色左侧边框，浅蓝色背景
表格浅色边框，粗体表头行
链接蓝色（#0066cc）

Customizing the Document

自定义文档

The user can override pandoc variables with 
-V key=value
:
VariableDefaultDescription
papersize
a4
Page size (
a4
, 
us-letter
, etc.)
fontsize
10pt
Base font size
template
whitepaper.typ
Typst template file
mainfont
Source Sans 3
Main body font
用户可通过
-V key=value
覆盖pandoc变量：
变量默认值描述
papersize
a4
页面尺寸（
a4
、
us-letter
等）
fontsize
10pt
基础字号
template
whitepaper.typ
Typst模板文件
mainfont
Source Sans 3
正文主字体

Requirements

要求

  • pandoc
    and 
    typst
    must be installed (the skill auto-installs them if missing)
    • macOS: via Homebrew (
      brew
      )
    • Linux: 
      pandoc
      via 
      apt-get
      , 
      typst
      via GitHub release binary
  • Source Sans 3 fonts are included in the plugin's 
    fonts/
    directory
  • 必须安装
    pandoc
    和
    typst
    （如果缺失，本Skill会自动安装）
    • macOS：通过Homebrew（
      brew
      ）安装
    • Linux：
      pandoc
      通过
      apt-get
      安装，
      typst
      通过GitHub发布的二进制文件安装
  • Source Sans 3字体包含在插件的
    fonts/
    目录中

Troubleshooting

故障排除

If fonts are not found by typst, ensure the 
TYPST_FONT_PATHS
environment variable is set correctly:
bash
export TYPST_FONT_PATHS=${CLAUDE_PLUGIN_ROOT}/fonts
IssueSolution
Font not foundCheck TYPST_FONT_PATHS points to plugin's fonts/ directory
Template not foundEnsure whitepaper.typ was copied to output directory
Tables not breakingTemplate handles this automatically
Missing title pageCheck frontmatter has 
title
field
如果typst找不到字体，请确保
TYPST_FONT_PATHS
环境变量设置正确：
bash
export TYPST_FONT_PATHS=${CLAUDE_PLUGIN_ROOT}/fonts
问题解决方案
字体未找到检查TYPST_FONT_PATHS指向插件的fonts/目录
模板未找到确保whitepaper.typ已复制到输出目录
表格未分页模板会自动处理此问题
缺少标题页检查前置内容是否包含
title
字段