# Sunge Latex PDF

> 将中文 Markdown、公众号文章或 Obsidian 笔记生成高质量 LaTeX PDF，提供孙割原版、界面志、屏幕图录三套风格，并完整处理网络图片、本地图片、Obsidian 图片、中文代码、表格和公式。用户提到 LaTeX 排版、Markdown 转 PDF、孙割模板、批量生成多种 PDF、中文 PDF 缺字或图片进入 PDF 时，应使用本 Skill。

- Skill: `tjxj/sunge-latex-pdf` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add tjxj/sunge-latex-pdf`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tjxj/sunge-latex-pdf/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tjxj (https://skillmd.com/u/tjxj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tjxj/sunge-latex-pdf

---


# 孙割 LaTeX PDF

把一份 Markdown 生成一套或三套中文 PDF。生成过程只使用本 Skill 自带的脚本、字体和模板。

## 三套风格

| 参数 | 名称 | 适合内容 |
|---|---|---|
| `sun` | 孙割原版 | 文字为主的小开本，保留 5×8 英寸、红黑封面和安静书页 |
| `journal` | 界面志 | 图文、代码比例接近的中文技术长文，默认推荐 |
| `atlas` | 屏幕图录 | 界面截图、宽表格和操作教程，横屏阅读 |
| `all` | 三套全部生成 | 对比风格或一次交付多个版本 |

孙割原项目正文没有图片规则。本 Skill 的 `sun` 风格重新实现了正文图片与图注，并让宽图按小开本正文宽度完整缩放，同时保留原版视觉。

## 执行流程

1. 确认输入 Markdown 的绝对路径
2. 运行 `scripts/doctor.sh` 检查 Pandoc、XeLaTeX、ImageMagick、Poppler 和内置字体
3. 根据用户指定选择风格；没有指定时使用 `journal`
4. 调用 `scripts/build.sh` 生成 PDF
5. 检查构建输出中的页数、中文数量、字体、图片数量、内容顺序和代码复制
6. 运行 `scripts/check_visual_layout.py` 检查标题字号、标题孤行、图注位置、图注大小和低内容空白页
7. 用 `pdftoppm` 渲染全部页面，实际查看封面、正文、代码、横图、竖图和最后一页
8. 发现缺字、空白图、裁切、重叠或页眉遮挡时，修复模板并重新生成

## 生成命令

指定一种风格：

```shell
bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style journal \
  --output "/绝对路径/输出/文章"
```

一次生成三套：

```shell
bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style all \
  --output "/绝对路径/输出/文章"
```

覆盖标题或作者：

```shell
bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style all \
  --output "/绝对路径/输出/文章" \
  --title "新的标题" \
  --author "作者名"
```

网络图片已经进入缓存后，可以增加 `--offline` 离线重建。需要目录时增加 `--toc`。

## 图片要求

支持以下写法：

```markdown
![网络图片](https://example.com/image.png)
![本地图片](assets/截图.png)
![[assets/设计图.png]]
![[assets/设计图.png|图片说明]]
```

图片处理遵循这些规则：

- 网络图片先下载并缓存
- 本地图片复制为安全文件名，允许中文和空格路径
- SVG、WebP、GIF 转成 XeLaTeX 可以处理的格式
- 图片保持比例，受最大宽度和最大高度双重限制
- 孙割原版中的宽图按正文宽度完整缩放，标题、说明和图片保持连续
- 图片与图注按同一中心线排列，三套模板的图注保持一致的阅读大小
- 有说明时生成图注，空说明时不生成空图注
- 缺图、下载失败或转换失败时中止并指出原地址
- 禁止静默丢图

## 中文要求

- 正文使用思源宋体
- 标题和图注使用思源黑体
- 代码中的中文使用霞鹜文楷等宽
- 三种字体随 Skill 提供并附许可证
- PDF 必须嵌入字体，中文必须能够复制和搜索
- 长命令与网址必须自动换行

## 验收命令

生成后运行：

```shell
python3 scripts/verify_pdf.py \
  --pdf "/绝对路径/文章-界面志.pdf" \
  --minimum-images 1
```

完整回归测试：

```shell
bash scripts/smoke-test.sh
```

固定案例是 `examples/deepseek-harness-plugins.md`。它包含 15 个标题、12 个代码块和 13 张网络图片，三套模板每次发布前都必须重新生成并逐页检查。

## 失败处理

- 缺少命令：运行 `scripts/doctor.sh`，按 README 安装
- 网络图片失败：报告具体 URL，网络恢复后重试；已有缓存时使用 `--offline`
- 中文缺字：检查 `assets/fonts` 三个字体文件，禁止退回系统默认字体
- 图片太小：优先使用 `atlas`；孙割原版优先保持小开本连续阅读
- 内容越界：保留构建目录 `--keep-build`，检查日志中的 `Overfull` 与 `Missing character`

交付前必须完成真实构建和可视检查。仅通过编译不代表完成。