markdown-to-pdf

快速摘要

目标： 将 Markdown 文件转换为 PDF，并支持语法高亮和自定义 CSS。

工作流：

1. 安装 -- 确保所需工具（pandoc + wkhtmltopdf 或 weasyprint）可用
2. 转换 -- 运行转换，并启用语法高亮和可选的 CSS
3. 验证 -- 检查 PDF 输出的格式和完整性

关键规则：

• 需要 pandoc + PDF 引擎（wkhtmltopdf 或 weasyprint）
• 支持对代码块进行语法高亮
• 可以应用自定义 CSS 进行样式设置

保持质疑。运用批判性思维和顺序思维。每项声明都必须有可追溯的证据，并附上置信度百分比（构想应高于 80%）。

markdown-to-pdf

将 Markdown 文件转换为高质量的 PDF 文档，并支持代码语法高亮和自定义 CSS。

需要安装

此技能需要 npm 依赖项。 运行以下任一命令：

# Option 1: Install via ClaudeKit CLI (recommended)
ck init  # Runs install.sh which handles all skills

# Option 2: Manual installation
cd .claude/skills/markdown-to-pdf
npm install

依赖项： md-to-pdf、gray-matter

注意： 首次运行时可能会下载 Chromium（约 150MB），除非检测到系统已安装 Chrome。

快速开始

# Basic conversion
node .claude/skills/markdown-to-pdf/scripts/convert.cjs --input ./README.md

# Specify output path
node .claude/skills/markdown-to-pdf/scripts/convert.cjs --input ./doc.md --output ./output.pdf

# With custom CSS
node .claude/skills/markdown-to-pdf/scripts/convert.cjs --input ./doc.md --css ./my-style.css

CLI 选项

选项	简写	描述	默认值
--input	-i	输入 Markdown 文件路径	（必填）
--output	-o	输出 PDF 文件路径	{input}.pdf
--css	-c	自定义 CSS 文件路径	内置
--no-highlight		禁用语法高亮	false
--help	-h	显示帮助信息

功能

• 语法高亮： 使用 highlight.js 渲染代码块
• 自定义 CSS： 使用自定义 CSS 覆盖默认样式
• 跨操作系统： 支持 Windows、macOS、Linux
• 系统 Chrome： 如果已安装 Chrome/Chromium，则使用系统版本
• Frontmatter 支持： 提取 YAML frontmatter 作为标题/元数据

默认样式

默认 PDF 样式包括：

• 正文使用衬线字体（Georgia）
• 代码使用等宽字体（Consolas/Monaco）
• 合理的页边距（2cm）
• 代码块背景高亮
• 表格边框和交替行颜色

输出

成功时返回 JSON：

{
    "success": true,
    "input": "/path/to/input.md",
    "output": "/path/to/output.pdf",
    "pages": 3
}

故障排除

未找到 Chrome： 此技能会自动下载 Chromium。设置 PUPPETEER_SKIP_DOWNLOAD=1 可阻止下载。

内存问题： 大型文档可能需要更多内存。可以考虑将文档拆分为多个文件。

字体问题： 通过 CSS @font-face 嵌入 Base64 编码字体，以确保渲染效果一致。

---

[IMPORTANT] 开始前使用 TaskCreate 将所有工作拆分为小任务——包括为每个文件读取创建任务。这可以避免长文件导致上下文丢失。对于简单任务，AI 必须主动询问用户是否跳过。 AI 错误预防 — 每项任务都要避免以下失败模式：

上下文变化后重新阅读文件。 上下文压缩、恢复工作或长时间运行的任务都可能导致记忆过时；行动前请核实当前文件。 根据源证据核实生成的内容。 AI 会幻觉出 API、名称、声明和文档事实。记录或引用前，请检查相关来源。 删除或重命名前检查下游引用。 移除某项内容可能导致文档、生成的镜像、配置和调用方过时；请先梳理引用关系。 编辑后追踪完整影响链。 更改定义可能会遗漏派生输出和使用方。在宣布完成前，请追踪受影响的链路。 核实所有受影响的输出，而不只是第一个。 一个检查通过不代表所有检查都通过；请验证更改可能影响的每个输出界面。 假定现有值是有意设置的——更改或指出缺陷前，先询问原因。 更改或报告常量、限制、标志、阈值、措辞或模式前，请阅读附近的上下文和历史记录、调用方的执行顺序，以及至少 2 个遵循相同惯例的同类调用点。文档只说明“是什么”却没有说明“为什么”，意味着缺少依据，而不是证明缺少防护措施。 行动前先指出歧义，不要默默做出选择。 存在多种有效解释时，必须明确提问，或说明所采用的假设及其风险。 断言系统负责的结果，而非基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态，绝不能断言由共享基础设施维护的投递／重试记录，因为任何同时运行的进程都可能写入这些记录。这类检查单独运行时会通过，但只要有其他进程共享该基础设施，就会变得不稳定。 确保共享指导与角色相关。 通用指导必须对每个接收该指导的技能或 Agent 都有帮助；针对代码的要求只应放在针对代码的规程中。

批判性思维方式 — 运用批判性思维和序贯思维。每项声明都需要有可追溯的证据，置信度 >80% 时才能采取行动。 防止幻觉： 绝不要把猜测当作事实；每项声明都要引用来源；坦诚承认不确定性；自行检查输出中的错误；独立交叉核对；对自己的判断保持怀疑——没有证据的确定性是一切幻觉的根源。

务必注意：运用批判性思维和序贯思维——每项声明都必须有适当且可追溯的证据（关于仓库／代码的声明需提供 file:line；关于研究、产品、内容和文档的声明需提供源 URL 或内容所在章节）；置信度 >80% 时才能采取行动，<60% 时切勿提出建议。防止幻觉：绝不要把猜测当作事实；坦诚承认不确定性；独立交叉核对；对自己的判断保持怀疑。

务必注意：遵循 AI 错误预防要求——根据证据核实生成的内容，删除或重命名前追踪下游引用，核实所有受影响的输出，在上下文丢失后重新阅读文件，并在行动前指出歧义。

项目协议叠加规则 — 执行此技能前，请先解析叠加于此技能之上的任何项目规则：将此技能名称与项目技能协议索引（默认路径为 docs/project-reference/skill-protocols-reference.md；若 docs/project-config.json 中有 referenceDocs 条目，则以其指定路径为准）的 Target 列进行匹配，且仅采用最具体的匹配层级——精确名称 > glob > *。此优先级只用于排列各叠加规则之间的顺序，绝不用于凌驾于此技能之上。仅读取匹配条目的正文，路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接只是显示文本，绝不是读取路径。若匹配的正文缺失或格式错误，应报告并跳过——绝不能根据索引中的 Description 重建。没有索引或没有匹配项时 -> 不应用叠加规则，且不作说明。完整约定见 .claude/skills/project-skill-protocol/references/registry.md。

叠加规则仅可添加内容：它们只能在此技能自身的协议之上增加规则，绝不能替换、覆盖、禁用或重新解释其中已有的规则——移除所有叠加规则后，此技能必须恢复为与其文档所述行为完全一致。叠加规则是简报，不是权限升级：它们绝不能豁免工作流关卡、git 规范、审核关卡或用户确认关卡。若叠加规则与技能之间确实存在冲突，或两个具体程度相同的叠加规则直接矛盾 -> 将两者都提交给用户；绝不能默默自行裁定。

**务必注意：**执行前，先解析此技能的项目协议叠加规则——仅采用最具体的匹配层级（精确名称 > glob > *；此顺序只用于排列叠加规则之间的优先级，绝不用于凌驾于此技能之上）；仅读取 <protocols-dir>/<Name>.md 下匹配条目的正文；若正文缺失或格式错误，应报告，绝不能重建。叠加规则仅可添加内容（绝不替换此技能自身的规则），且只是简报，绝不是权限升级；具体程度相同的规则若相互矛盾，应交由用户处理。

收尾提醒

重要，务必注意——当前生效的协议（此技能所包含 SYNC/共享区块的简要摘要）：

• **批判性思维：**每项主张都要提供可追溯至 file:line 的证据；置信度需 >80% 才能采取行动；绝不能将猜测说成事实。
• **防止 AI 出错：**依据证据验证生成内容，追踪下游引用，验证所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。

**重要，务必注意：**开始前，使用 TaskCreate 将工作拆分为小型待办任务 **重要，务必注意：**创建新代码前，在代码库中搜索至少 3 个相似模式 **重要，务必注意：**每项主张都要引用 file:line 证据（置信度需 >80% 才能采取行动） **重要，务必注意：**添加最终审核待办任务，以验证工作质量

**[TASK-PLANNING]**采取行动前，分析任务范围，并使用 TaskCreate 系统地将其拆分为小型待办任务和子任务。