Markdown to PDF Skill (v2.0)

将 Markdown 文档转换为专业的苹果设计风格 PDF 白皮书。

版本更新

v2.0 (2025-01-30)

重大改进:

• ✅ 使用 pdfkit + wkhtmltopdf 替代 WeasyPrint

• ✅ 移除 pango 依赖,安装更简单

• ✅ 支持 WebP 图片格式

• ✅ 自动处理无扩展名图片

• ✅ 添加完整图片处理工具链

• ✅ 提供一键式工作流

依赖变更:

旧版本 (v1.0)

pip3 install markdown2 weasyprint brew install pango # 复杂

新版本 (v2.0)

pip3 install markdown pdfkit Pillow brew install wkhtmltopdf # 简单

核心功能

• 专业排版: 书籍级排版质量,自动处理分页、孤行寡行

• 苹果设计: SF 字体系统、现代简洁风格、专业配色

• 完整目录: 自动提取章节结构,双列布局,可点击跳转

• Markdown 完美支持: 代码块、表格、引用、列表等全部正确渲染

• 图片处理: 自动检测和转换 WebP 图片,处理无扩展名图片

• 一键工作流: 从图片处理到 PDF 生成的完整自动化流程

使用方法

方式 1: 基础转换

转换单个文件

python scripts/convert.py input.md

指定输出文件名

python scripts/convert.py input.md -o "我的白皮书.pdf"

自定义标题和作者

python scripts/convert.py input.md --title "技术白皮书" --author "花叔"

方式 2: 完整工作流 (推荐)

一键执行: 图片处理 + PDF 生成

python scripts/workflow.py input.md

跳过图片处理

python scripts/workflow.py input.md --skip-images

完整自定义

python scripts/workflow.py input.md
--title "技术白皮书"
--author "团队"
-o "output.pdf"

方式 3: 分步执行

步骤 1: 分析图片格式

python scripts/analyze_images.py

步骤 2: 转换 WebP 图片

python scripts/batch_convert_images.py

步骤 3: 更新 Markdown 引用

python scripts/update_markdown_refs.py

步骤 4: 生成 PDF

python scripts/convert.py input.md

Markdown 文档要求

你的 Markdown 文档应该遵循以下结构:

文档标题

1. 第一章

1.1 第一节

1.2 第二节

2. 第二章

2.1 第一节

关键规则:

• 主章节: ## 1. 标题 (数字 + 点 + 空格 + 标题)

• 子章节: ### 1.1 标题 (数字.数字 + 空格 + 标题)

• 这样才能正确提取目录

工具说明

convert.py - 核心转换工具

将 Markdown 转换为 PDF,支持:

• 元数据提取 (标题、作者、日期等)

• 目录生成 (双列布局)

• 图片路径处理 (绝对路径 + 扩展名补全)

• 苹果设计风格 CSS

analyze_images.py - 图片格式分析

检测图片实际格式:

• 通过 Magic Bytes 检测真实格式

• 识别无扩展名的 WebP

• 识别错误扩展名的 WebP

• 生成转换计划报告

batch_convert_images.py - 批量图片转换

批量转换 WebP 为 PNG:

• 根据转换计划执行

• 自动删除原 WebP 文件

• 生成文件名映射表

• 生成转换报告

update_markdown_refs.py - 引用更新

更新 Markdown 中的图片引用:

• 支持 HTML img 标签

• 支持 Markdown 图片语法

• 根据映射表批量替换

• 生成更新报告

workflow.py - 完整工作流

一键执行所有步骤:

• 自动分析图片

• 自动转换格式

• 自动更新引用

• 自动生成 PDF

设计特点

封面设计

• 淡灰色渐变背景

• 大标题: 64pt,简洁现代

• 副标题和元信息

目录设计

• 双列布局,单页展示

• 主章节粗体,子章节缩进

• 可点击跳转到对应章节

正文排版

• SF 字体系列 (苹果设计语言)

• 行高 1.7,舒适阅读

• 章节自动分页

• 孤行寡行控制

代码块

• 浅灰背景 + 细边框

• 圆角 8px

• SF Mono 等宽字体

• 自动避免分页

表格

• 清晰网格线

• 浅灰表头

• 自动保留表头 (长表格分页时)

依赖安装

Python 依赖

pip3 install markdown pdfkit Pillow

系统依赖

macOS

brew install wkhtmltopdf

Linux

sudo apt-get install wkhtmltopdf

或下载二进制: https://wkhtmltopdf.org/downloads.html

常见问题

Q: 目录为什么是空的?

A: 确保你的 Markdown 使用了正确的章节格式:

• 1. 标题

而不是 ## 标题

• 1.1 标题

而不是 ### 标题

Q: 代码块显示不正确?

A: 确保使用三个反引号包裹:

def hello():
    print("Hello")

Q: 表格格式乱了?

A: 使用标准的 Markdown 表格语法:

Q: wkhtmltopdf 安装失败?

A:

macOS

brew install wkhtmltopdf

Linux

sudo apt-get install wkhtmltopdf

或下载二进制

https://wkhtmltopdf.org/downloads.html

Q: 图片显示不正确?

A: 使用完整工作流:

python scripts/workflow.py input.md

它会自动处理所有图片问题。

Q: 如何从 v1.0 升级?

A: 查看 UPGRADE.md 文档了解详细升级步骤。

配置选项

如果需要自定义样式,可以修改 scripts/convert.py 中的 CSS 变量:

主色调

PRIMARY_COLOR = '#06c' # 苹果蓝 TEXT_COLOR = '#1d1d1f' # 主文本黑色 GRAY_COLOR = '#86868b' # 浅灰色

字体大小

COVER_TITLE_SIZE = '64pt' H2_SIZE = '22pt' H3_SIZE = '17pt' BODY_SIZE = '11pt'

文件结构

.claude/skills/markdown-to-pdf/ ├── SKILL.md # 本文件 ├── README.md # 快速开始 ├── EXAMPLES.md # 使用示例 ├── UPGRADE.md # 升级指南 ├── WORKFLOW.md # 工作流文档 └── scripts/ ├── convert.py # 核心转换工具 ├── analyze_images.py # 图片分析 ├── batch_convert_images.py # 批量转换 ├── update_markdown_refs.py # 引用更新 └── workflow.py # 完整工作流

技术实现

本 Skill 使用:

• markdown: 官方 Markdown 解析库

• pdfkit: HTML to PDF 转换 (基于 wkhtmltopdf)

• Pillow: 图片处理和格式转换

• 苹果设计系统: SF 字体、专业配色、现代排版

更新日志

v2.0 (2025-01-30)

• 使用 pdfkit 替代 WeasyPrint

• 移除 pango 依赖

• 添加图片处理工具链

• 添加完整工作流

• 改进图片路径处理

• 改进错误提示

v1.0 (2025-12-24)

• 初始版本

• 支持完整 Markdown 语法

• 苹果设计风格

• 自动目录生成

• 书籍级排版质量