| name | md-to-minimal-pdf |
| description | 将 Markdown 技术教程转换为排版精美的 PDF 文档。基于 HTML + CSS + Paged.js 工作流， 提供瑞士极简风格的封面、目录页、章节分页、三线表、代码块跨页、页眉页脚等完整排版系统。 触发条件：用户要求将 Markdown 教程/文档/指南转换为 PDF，或需要排版技术文档、 教程手册、学习指南等长文档时。也适用于用户明确要求"做成 PDF"、"排版"、 "生成文档"的场景。
|
MD 转简约风 PDF
将 Markdown 格式技术教程转换为专业排版的 PDF 文档。
工作流程
Markdown 源文件
│
├─ 1. Markdown → HTML（scripts/md_to_pdf.py）
│ - 解析标题层级
│ - 包裹章节标题为 chapter-opener
│ - 处理参考文献区块
│
├─ 2. 套入模板（assets/template.html）
│ - 替换封面信息（标题/作者/日期）
│ - 插入目录条目
│ - 嵌入正文 HTML
│
└─ 3. HTML → PDF（Paged.js）
- 分页渲染
- 生成页眉页脚
- 输出最终 PDF
使用方法
命令行
python scripts/md_to_pdf.py input.md output.pdf [作者] [日期]
参数说明：
input.md：Markdown 源文件路径output.pdf：输出 PDF 路径作者（可选）：封面作者名日期（可选）：封面日期，如 "2026年5月"
Markdown 格式要求
源文件需遵循以下结构：
# 文档标题（显示在封面，正文中自动删除）
> 简短描述（显示在封面副标题）
---
## 1. 第一章标题
正文内容...
### 1.1 小节
内容...
## 2. 第二章标题
...
## 参考资料
参考文献列表...
关键规则：
- 一级标题
# 仅用于文档主标题，会显示在封面上
- 二级标题
## 必须以 数字. 开头（如 ## 1. 标题），用于章节编号
- 三级
### 和四级 #### 标题正常使用
- 代码块使用围栏式（```）
- 表格使用标准 Markdown 表格语法
- 最后一个
## 标题如果是"参考资料"/"参考文献"，会自动包裹特殊样式
文件结构
pdf-tutorial-publisher/
├── SKILL.md ← 本文件
├── scripts/
│ └── md_to_pdf.py ← Markdown → PDF 转换脚本
├── assets/
│ └── template.html ← HTML/CSS 排版模板
└── references/
└── style-reference.md ← CSS 参数详细说明
资源说明
| 文件 | 类型 | 用途 |
|---|
scripts/md_to_pdf.py | 脚本 | 执行转换，读取 template.html，调用 pdf.sh |
assets/template.html | 资产 | 包含完整 CSS 样式的 HTML 模板，不加载到上下文 |
references/style-reference.md | 参考 | CSS 参数速查和自定义指南 |
自定义排版
修改 assets/template.html 中的 CSS 参数。详细参数表见 references/style-reference.md。
常见自定义
修改封面颜色：将所有 #1a1a1a 替换为目标主色。
调整正文字号：修改 .content { font-size: 10pt; }。
调整页边距：修改 @page { margin: 2.0cm 1.8cm 2.5cm 1.8cm; }。
调整代码块大小：修改 pre { font-size: 7.5pt; line-height: 1.2; }。
关键约束
跨页与空白页
| 元素 | page-break-inside | 说明 |
|---|
代码块 pre | auto | 必须允许跨页，否则产生大量空白 |
表格 table | avoid | 表格保持完整不跨页 |
图片 figure | avoid | 图片不跨页 |
章节标题 .chapter-opener | 外部用 page-break-before: always | 每章新开一页 |
页眉页脚
- 封面页和目录页自动隐藏页眉页脚
- 正文页眉自动显示当前章节名（通过
string-set: doctitle content() 绑定 h2）
- 页码居中显示，带左右装饰线
三线表规范
表格自动应用学术三线表样式：
- 表头顶线 1.5pt，底线 0.8pt
- 行间细线 0.3pt
- 表格底线 1.5pt
- 无竖线
依赖
- Python 3 +
markdown 库
- Node.js + Playwright + Chromium
- pdf skill 的
scripts/pdf.sh 或 scripts/html_to_pdf.js
脚本按以下顺序查找 PDF 工具：
- 环境变量
PDF_SKILL_PATH 指定的目录
- skill 同级目录下的
pdf/ 目录
/app/.agents/skills/pdf/（默认安装路径）
找不到 PDF 工具时会输出 HTML 文件并报错。
安装：
pip install markdown
npm install -g playwright
npx playwright install chromium
