md2pdf

将 Markdown 渲染为排版精美的 PDF，支持封面/目录/书签/页码/KaTeX/Mermaid/代码高亮。 Render Markdown to beautifully typeset PDF. Cover/TOC/bookmarks/page numbers/KaTeX/Mermaid/highlighting.

md2pdf — Markdown 转 PDF

将 Markdown 文件转换为排版精美的 PDF，不依赖 AI 语义理解。

---

Skill 初始化

当此 Skill 首次加载时，执行以下步骤：

1. 环境检测

bash

python3 scripts/md2pdf.py --validate

输出示例：

text

=======================================================
  md2pdf — 环境检测
  语言环境: 🇨🇳 中文
=======================================================
  ✅ pandoc: pandoc 2.12
    路径: /opt/homebrew/bin/pandoc
  ✅ 系统浏览器: Google Chrome 128.0.6613.137
    路径: /Applications/Google Chrome.app/...
  ✅ Playwright: via /usr/bin/python3
    路径: /usr/bin/python3
  ✅ Chromium: Playwright 内置 Chromium 就绪

  🎨 可用主题: default, academic
  🟢 环境就绪，可以转换。

2. 安装缺失组件（如需）

如果环境检测失败，依次安装缺失组件：

缺失 pandoc： 运行 brew install pandoc

缺失 Playwright + Chromium：

• 英文语境：pip install playwright && playwright install chromium
• 中文/国内用户，建议使用镜像源加速：

  bash

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

AI 应检测用户的语言环境（如 LANG=zh_CN），自动选择是否显示镜像源提示。

2. 用户偏好配置

3. 用户偏好配置

主动询问用户以下偏好，写入 output/user-config.json：

json

{
  "theme": "default",
  "font_size": 14,
  "page_size": "A4",
  "toc": true,
  "cover": true,
  "toc_depth": 4
}

如果用户跳过配置，使用上述默认值。

3. 输出目录

• 生成的 PDF 存储在 output/ 目录下
• 如果用户指定了输出路径，则以用户指定的为准
• output/ 中的文件不会被 git 跟踪（仅保留 .gitkeep）

---

能力边界

擅长	不擅长
Markdown → PDF 转换	合并多个 MD 为单个 PDF
封面页（从 front-matter 自动生成）	从零创建 PDF（请先写 MD）
交互式目录 + PDF 侧边栏书签	分栏布局
页码、多主题切换（default/academic）	动态页眉页脚自定义
中文排版增强（--chinese-layout）	加密/水印/签名 PDF
KaTeX 数学公式（pandoc --katex）	复杂 LaTeX 数学环境
Mermaid 图表（注入 mermaid.js 渲染）	动态/交互式图表
代码语法高亮（highlight.js，190+ 语言）	—
智能分页（H1 另起页、代码块/表格保持完整）	—
自定义字号和纸张大小	深度排版控制
环境自检（--validate）	—

---

输入

Markdown front-matter（封面数据）

在 MD 文件头部使用 YAML 格式声明封面信息，所有字段均为可选：

yaml

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

CLI 参数

参数	是否必需	说明
--input <path>	✅	输入 Markdown 文件路径
--output <path>	❌	输出 PDF 路径，不指定则自动生成
--theme <name>	❌	主题：default / academic，默认 default
--chinese-layout	❌	叠加中文排版增强（行距、缩进、禁则），配合任意主题
--cover / --no-cover	❌	是否生成封面页，默认开启。无 front-matter 时自动用文件名
--toc / --no-toc	❌	是否生成目录，默认开启
--toc-depth <n>	❌	目录深度 1-6，默认 4
--font-size <px>	❌	正文字号，默认 14px
--font-family <name>	❌	正文字体，覆盖主题默认字体
--page-size <format>	❌	A4 / A3 / letter / legal，默认 A4
--katex	❌	启用 KaTeX 数学公式渲染
--mermaid	❌	启用 Mermaid 图表渲染
--highlight / --no-highlight	❌	代码语法高亮（highlight.js），默认开启
--header <text> / --no-header	❌	自定义页眉文字，默认从 config.json 读取
--watermark <text> / --no-watermark	❌	水印文字（半透明平铺），默认从 config.json 读取
--password <pwd>	❌	PDF 打开密码（需安装 pikepdf）
--validate	❌	环境检测模式，不执行转换
--list-themes	❌	列出可用主题

---

工作流

第 0 步：初始化配置（首次使用）

检查 config.json 中页眉/水印/加密的默认值是否已设置。若均为空，引导用户选择：

1. 页眉：是否需要默认页眉？如"XX公司 · 内部文档"
2. 水印：是否需要默认水印？如"机密"、"DRAFT"
3. 加密：是否默认加密？（建议默认关闭）

如果用户启用水印或加密，先检查依赖：

• 水印依赖 PyMuPDF（python3 -c "import fitz"）
• 加密依赖 pikepdf（python3 -c "import pikepdf"）
• 若缺失，提示安装命令（pip install pymupdf / pip install pikepdf）

用户也可在后续每次转换时通过 --header、--watermark、--password 显式覆盖。

第 1 步：确认需求

确认用户提供的 Markdown 文件路径，确认是否需要封面、目录、主题、中文排版、页眉、水印、加密等。

主题和排版：

• --theme default：苹果风格（默认）
• --theme academic：学术风格
• --chinese-layout：叠加中文排版增强（2倍行距、首行缩进、禁则处理），可配合任意主题

封面行为（智能默认）：

• 如果 MD 文件头部有 YAML front-matter 的 title 字段 → 以此为封面标题
• 如果 MD 没有 front-matter → 自动用文件名作为封面标题（如 技术方案.md → 封面显示"技术方案"）
• 如果用户不需要封面 → 传 --no-cover

如果用户想要更丰富的封面信息，指导其添加 front-matter：

yaml

---
title: "报告标题"
author: "作者"
date: "2026-06-26"
---

第 2 步：环境检测

首次使用或环境变更后，先运行环境检测：

bash

python3 scripts/md2pdf.py --validate

输出示例：

text

=======================================================
  md2pdf — 环境检测
=======================================================
  ✅ pandoc: pandoc 2.12
    路径: ...
  ✅ Playwright: Version 1.56.0
    路径: ...
  ✅ Chromium: 就绪

  🎨 可用主题: default, academic
  🟢 环境就绪，可以转换。

环境不完整时：

• pandoc 缺失 → brew install pandoc
• Playwright 缺失 → pip install playwright && playwright install chromium

第 3 步：执行转换

bash

# 基本用法（AI 拼装命令后执行）
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

# 自定义字号和纸张
python3 scripts/md2pdf.py --input doc.md --font-size 16 --page-size A3

# 无封面、无目录的简洁模式
python3 scripts/md2pdf.py --input doc.md --no-cover --no-toc

# 启用 KaTeX 数学公式
python3 scripts/md2pdf.py --input doc.md --katex

# 启用 Mermaid 图表
python3 scripts/md2pdf.py --input doc.md --mermaid

# 同时启用 KaTeX + Mermaid
python3 scripts/md2pdf.py --input doc.md --katex --mermaid

第 4 步：验证输出

转换完成后确认：

• PDF 文件已生成
• 文件大小不为 0（一般 300KB+）
• 封面/目录/页码是否按预期生成
• 打开确认排版无误，侧边栏有 PDF 书签

如果出现异常： 脚本已输出带常见原因的错误信息。若需进一步排查，查阅 docs/FAQ.md。

---

架构

text

管线: Markdown → 解析 front-matter → pandoc (--toc, --katex) →
      注入封面 HTML → 注入 CSS 主题 → 注入 Mermaid.js/highlight.js（本地缓存）→
      Playwright PDF (等待 Mermaid 渲染 → 输出)
         ↑                                    ↑
    commonmark_x 解析                    outline + 页脚模板

为什么这样设计：

• pandoc 处理 Markdown 解析，不依赖 AI 理解
• Playwright 使用真实 Chromium 浏览器渲染，输出与预览一致
• 封面/目录/页码全部由脚本自动处理，无需 AI 干预
• PDF 书签（outline）让阅读器侧边栏可交互跳转
• Mermaid.js、highlight.js 首次自动下载并本地缓存，后续离线可用
• 无 front-matter 时封面自动用文件名，不会出现空白页
• 分页保护：代码块/表格/引用/图表保持完整，标题不孤行
• 结果可复现：同一份 MD 每次输出完全相同的 PDF

PDF 交互特性

特性	说明
📑 可点击目录页	TOC 中的条目可点击跳转到对应章节
📌 侧边栏书签	Playwright outline: true 生成 PDF 书签树
🔢 居中页码	每页底部自动显示页码

---

输出

转换成功后输出：✅ 转换完成: /path/to/output.pdf (629 KB)

失败时输出错误信息到 stderr，退出码为 1。

输出路径规则

条件	输出路径
用户指定了 --output	以用户指定为准
未指定 --output，MD 文件在本项目外	MD 同目录下同名 .pdf
未指定 --output，MD 文件在技能目录内	output/<文件名>.pdf

---

常见问题

转换异常或结果不符合预期时，第一时间查阅 docs/FAQ.md。

该文件覆盖：

• 转换超时 / PDF 未生成 / 页数异常
• 封面空白 / 目录为空 / 主题不对
• 中文方块 / 字体选择 / Mermaid/KaTeX 不渲染
• 错误信息解读（pandoc 失败、Playwright 失败等）

FAQ 中的每个条目均包含原因分析和可执行的解决方案，AI 可直接引用回复用户。