huashu-md-to-pdf

1# Markdown to PDF Skill
2 
3将 Markdown 文档转换为专业的苹果设计风格 PDF 白皮书。
4 
5## 核心功能
6 
71. **专业排版**：书籍级排版质量，自动处理分页、孤行寡行
82. **苹果设计**：SF 字体系统、现代简洁风格、专业配色
93. **完整目录**：自动提取章节结构，双列布局，可点击跳转
104. **Markdown 完美支持**：代码块、表格、引用、列表等全部正确渲染
11 
12## 使用方法
13 
14### 基础用法
15 
16```bash
17# 转换单个文件
18python scripts/convert.py input.md
19 
20# 指定输出文件名
21python scripts/convert.py input.md -o "我的白皮书.pdf"
22 
23# 自定义标题和作者
24python scripts/convert.py input.md --title "技术白皮书" --author "花叔"
25```
26 
27### 图片路径
28 
29Markdown 里的相对路径图片，是**相对 md 文件自身所在目录**解析的，目录名和文件名带中文都可以：
30 
31```markdown
32![示意图](图片/架构图.png)     ← 和 md 文件同级的「图片」目录
33![示意图](./assets/arch.png)
34```
35 
36找不到的图片会在转换时打印警告并列出路径。以前这种情况是静默跳过的，PDF 照样生成、只是没有图。
37 
38### 已知未解决：某些环境下 macOS「预览」打开是乱码
39 
40有用户报告生成的 PDF 在 macOS「预览」里是乱码，浏览器打开正常。**这个问题还没有解决办法**，原因也还没定位——在一台用 Arial Unicode MS 渲染中文的机器上复现不出来，而报告者的字体环境和 weasyprint 版本都不清楚。
41 
42**不要试图用 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ě 据⊤」。它让问题更糟，不是逃生出口。
43 
44碰到乱码时可以先试：升级 weasyprint、或在 CSS 里换一个非 collection 的字体。
45 
46### Markdown 文档要求
47 
48你的 Markdown 文档应该遵循以下结构：
49 
50```markdown
51# 文档标题
52 
53## 1. 第一章
54### 1.1 第一节
55### 1.2 第二节
56 
57## 2. 第二章
58### 2.1 第一节
59```
60 
61**关键规则**：
62- 主章节：`## 1. 标题`（数字 + 点 + 空格 + 标题）
63- 子章节：`### 1.1 标题`（数字.数字 + 空格 + 标题）
64- 这样才能正确提取目录
65 
66## 设计特点
67 
68### 封面设计
69- 淡灰色渐变背景
70- 大标题：64pt，简洁现代
71- 副标题和元信息
72 
73### 目录设计
74- 双列布局，单页展示
75- 主章节粗体，子章节缩进
76- 可点击跳转到对应章节
77 
78### 正文排版
79…