前言¶

技术文档、方案说明、读书笔记往往先写在 Markdown 里，真正要发给同事或归档时，还需要一份版式稳定、带目录和页码的 PDF。手工用编辑器导出，或自己拼 pandoc、浏览器打印脚本，步骤多、环境杂，也很难在对话里一句话完成。

下面介绍 SkillHub 上的 md2pdf / Markdown 转 PDF（坐标 @user_48539314/md2pdf-chrome，当前版本 1.7.0）。它把「检测环境 → 按参数转换 → 校验输出」写进标准 SKILL.md 工作流，让 Cursor、Claude Code 等支持 Skills 的客户端按同一套步骤执行，而不是每次临时摸索命令。

这是什么¶

md2pdf 是一个面向 AI Agent 的文档转换 Skill：读取本地 Markdown，经固定管线渲染为排版后的 PDF，不依赖模型去「理解」正文再排版。

• 维护信息：Skill 元数据作者为 CoderMoray；在 SkillHub 上由社区用户 user_48539314 发布，分类为 office-efficiency，来源为 community。
• 依赖特点：标签 requires_api_key=false，无需额外 API Key。
• 解决的问题：在 Agent 会话里完成 Markdown → PDF，并覆盖封面、目录、书签、页码，以及 KaTeX、Mermaid、代码高亮等常见技术写作需求。

官方入口：

• API / 安装坐标：https://api.skillhub.cn/user_48539314/md2pdf-chrome
• SkillHub 展示页：https://www.skillhub.cn/skills/user_48539314/md2pdf-chrome

核心功能¶

以下能力均来自 Skill 简介与 SKILL.md 中的能力说明，可按需组合 CLI 参数启用。

管线概要（Skill 文档描述）：Markdown → 解析 front-matter → pandoc（含 --toc、--katex）→ 注入封面与 CSS 主题 → 按需注入 Mermaid.js / highlight.js → Playwright 调用 Chromium 输出 PDF。同一份 Markdown 在相同参数下应得到可复现的结果。

能力边界（Skill 明确列出的「不擅长」项）：例如合并多个 MD 为单个 PDF、分栏版式、从零生成 PDF（需先有 Markdown）、复杂 LaTeX 环境、动态交互图表等，不宜强行用本 Skill 承担。

安装与启用¶

1. 安装 SkillHub CLI（若尚未安装）¶

按 SkillHub 官方安装说明检查 CLI：

command -v skillhub && skillhub --version

未安装时，可使用官方一键脚本（完整安装或仅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

说明见：https://skillhub.cn/install/skillhub.md。

2. 安装 md2pdf Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被客户端加载。

Cursor 示例（skills 目录为 ~/.cursor/skills/）：

skillhub install @user_48539314/md2pdf-chrome --dir ~/.cursor/skills/

Claude Code 示例：

skillhub install @user_48539314/md2pdf-chrome --dir ~/.claude/skills/

Codex 可使用 ~/.codex/skills/ 或项目下的 .agents/skills/（以你当前环境为准）。

也可以在对话中让 Agent 按 SkillHub 页面提示执行：先阅读 https://skillhub.cn/install/skillhub.md，再安装 @user_48539314/md2pdf-chrome。

3. 转换依赖（本机环境）¶

Skill 首次加载时会引导做环境检测。核心依赖为 pandoc 与 Playwright + Chromium（--validate 会检查系统浏览器与 Playwright 内置 Chromium 是否可用）。

环境检测命令（路径以 Skill 安装目录为准，文档中为 scripts/md2pdf.py）：

python3 scripts/md2pdf.py --validate

缺失组件时，Skill 文档给出的典型安装方式包括：

brew install pandoc

PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/playwright \
pip install playwright && playwright install chromium

国内用户可按 Skill 说明使用 PLAYWRIGHT_DOWNLOAD_HOST 镜像加速 Chromium 下载。

可选：首次使用可写入 output/user-config.json 记录主题、字号、纸张、是否封面/目录等默认偏好；页眉、水印、加密相关默认值可配置在 Skill 目录下的 config.json（见 SKILL.md 工作流第 0 步）。

典型用法¶

封面元数据¶

在 Markdown 顶部用 YAML 声明封面字段（均可选）：

---
title: "文档标题"
subtitle: "副标题（可选）"
author: "作者名"
date: "2026-06-26"
version: "1.7.0"
---

无 front-matter 时，Skill 会用文件名作为封面标题；若不需要封面，转换时加 --no-cover。

转换命令示例¶

在 Skill 目录下执行（或让 Agent 拼装等价命令）：

# 最简：输入 MD，输出路径按 Skill 规则自动生成
python3 scripts/md2pdf.py --input /path/to/doc.md

# 学术主题 + 中文排版
python3 scripts/md2pdf.py --input doc.md --theme academic --chinese-layout

# 调整目录深度，关闭封面
python3 scripts/md2pdf.py --input doc.md --no-cover --toc-depth 2

# 数学公式与 Mermaid 图
python3 scripts/md2pdf.py --input doc.md --katex --mermaid

指定输出文件：

python3 scripts/md2pdf.py --input doc.md --output /path/to/out.pdf

成功时脚本会输出类似：✅ 转换完成: /path/to/output.pdf (629 KB)。完成后建议打开 PDF，确认目录可点击、侧边栏书签、页码与版式是否符合预期。

适用场景与注意¶

适合谁

• 已在用 Agent 写或改 Markdown，需要稳定产出「可转发、可打印」的 PDF。
• 文档含代码块、表格、KaTeX 公式或 Mermaid 图，希望一条管线统一处理。
• 希望封面、目录、书签、页码由脚本生成，减少手工排版。

使用上需要注意

1. 环境体积：除 Skill 本体外，pandoc 与 Playwright/Chromium 会占用一定磁盘；--validate 可确认是否可复用本机 Chrome。
2. 工作目录：CLI 需在 Skill 安装目录内调用文档中的 scripts/md2pdf.py（或按 Agent 加载后的实际路径执行），并保证 themes/ 等资源可访问。
3. 输出位置：未指定 --output 时，规则为：项目外 MD → 同目录同名 .pdf；Skill 目录内 MD → output/<文件名>.pdf。
4. 边界：多文件合并、复杂版式定制等不在 Skill 声明的擅长范围内，应另选工具或先合并 Markdown。
5. 社区包：SkillHub 元数据显示来源为 community，安装前可在 SkillHub 页面查看版本与说明；当前抓取数据为评分 100000、下载 944（页面统计会更新）。

结尾¶

md2pdf / Markdown 转 PDF 把 Markdown 转 PDF 固化成 Agent 可执行的步骤：环境自检、pandoc 解析、Chromium 渲染，并覆盖封面、目录、书签、页码与常见技术写作元素。若你经常在对话里交付文档，值得在 SkillHub 安装 @user_48539314/md2pdf-chrome，并按 SKILL.md 跑通一次 --validate 与样例转换。

• 官方 API：https://api.skillhub.cn/user_48539314/md2pdf-chrome
• SkillHub：https://www.skillhub.cn/skills/user_48539314/md2pdf-chrome