# Huashu Md To PDF

将 Markdown 文档转换为专业的 PDF 白皮书，采用苹果设计风格。 支持完整的 Markdown 语法（代码块、表格、引用、列表等）。 自动生成封面、目录、页眉页脚。...

- Repository: https://github.com/alchaincyf/huashu-skills (2152 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add alchaincyf/huashu-skills --skill huashu-md-to-pdf -g -a claude-code -y`
Codex: `npx skills add alchaincyf/huashu-skills --skill huashu-md-to-pdf -g -a codex -y`
Cursor: `npx skills add alchaincyf/huashu-skills --skill huashu-md-to-pdf -g -a cursor -y`
Gemini CLI: `npx skills add alchaincyf/huashu-skills --skill huashu-md-to-pdf -g -a gemini-cli -y`

## Description

将 Markdown 文档转换为专业的 PDF 白皮书，采用苹果设计风格。 支持完整的 Markdown 语法（代码块、表格、引用、列表等）。 自动生成封面、目录、页眉页脚。 使用场景：技术文档、白皮书、教程、报告等需要专业排版的 Markdown 文档。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Markdown to PDF Skill

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

## 核心功能

1. **专业排版**：书籍级排版质量，自动处理分页、孤行寡行
2. **苹果设计**：SF 字体系统、现代简洁风格、专业配色
3. **完整目录**：自动提取章节结构，双列布局，可点击跳转
4. **Markdown 完美支持**：代码块、表格、引用、列表等全部正确渲染

## 使用方法

### 基础用法

```bash
# 转换单个文件
python scripts/convert.py input.md

# 指定输出文件名
python scripts/convert.py input.md -o "我的白皮书.pdf"

# 自定义标题和作者
python scripts/convert.py input.md --title "技术白皮书" --author "花叔"
```

### 图片路径

Markdown 里的相对路径图片，是**相对 md 文件自身所在目录**解析的，目录名和文件名带中文都可以：

```markdown
![示意图](图片/架构图.png)     ← 和 md 文件同级的「图片」目录
![示意图](./assets/arch.png)
```

找不到的图片会在转换时打印警告并列出路径。以前这种情况是静默跳过的，PDF 照样生成、只是没有图。

### 已知未解决：某些环境下 macOS「预览」打开是乱码

有用户报告生成的 PDF 在 macOS「预览」里是乱码，浏览器打开正常。**这个问题还没有解决办法**，原因也还没定位, , 在一台用 Arial Unicode MS 渲染中文的机器上复现不出来，而报告者的字体环境和 weasyprint 版本都不清楚。

**不要试图用 weasyprint 的 `full_fonts=True` 绕过它。** 实测：macOS 上的中文字体（PingFang.ttc、Songti.ttc、Hiragino Sans GB.ttc）都是 TrueType Collection，`full_fonts=True` 会把整个 collection 的原始字节塞进 PDF 的 `/FontFile2`（magic 是 `ttcf` 而不是合法的 `\x00\x01\x00\x00`），结果是**文件暴涨到几十 MB，而且照样乱码**, , 实测一段中文从 10 KB 变成 43 MB，渲染出来是「Oě 据⊤」。它让问题更糟，不是逃生出口。

碰到乱码时可以先试：升级 weasyprint、或在 CSS 里换一个非 collection 的字体。

### Markdown 文档要求

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

```markdown
# 文档标题

## 1. 第一章
### 1.1 第一节
### 1.2 第二节

## 2. 第二章
### 2.1 第一节
```

**关键规则**：
- 主章节：`## 1. 标题`（数字 + 点 + 空格 + 标题）
- 子章节：`### 1.1 标题`（数字.数字 + 空格 + 标题）
- 这样才能正确提取目录

## 设计特点

### 封面设计
- 淡灰色渐变背景
- 大标题：64pt，简洁现代
- 副标题和元信息

### 目录设计
- 双列布局，单页展示
- 主章节粗体，子章节缩进
- 可点击跳转到对应章节

### 正文排版
- SF 字体系列（苹果设计语言）
- 行高 1.7，舒适阅读
- 章节自动分页
- 孤行寡行控制

### 代码块
- 浅灰背景 + 细边框
- 圆角 8px
- SF Mono 等宽字体
- 自动避免分页

### 表格
- 清晰网格线
- 浅灰表头
- 自动保留表头（长表格分页时）

## 配置选项

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

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

# 字体大小
COVER_TITLE_SIZE = '64pt'
H2_SIZE = '22pt'
H3_SIZE = '17pt'
BODY_SIZE = '11pt'
```

## 常见问题

The rest: https://github.com/alchaincyf/huashu-skills/blob/HEAD/huashu-md-to-pdf/SKILL.md