| name | sunge-latex-pdf |
| description | 将中文 Markdown、公众号文章或 Obsidian 笔记生成高质量 LaTeX PDF,提供孙割原版、界面志、屏幕图录三套风格,并完整处理网络图片、本地图片、Obsidian 图片、中文代码、表格和公式。用户提到 LaTeX 排版、Markdown 转 PDF、孙割模板、批量生成多种 PDF、中文 PDF 缺字或图片进入 PDF 时,应使用本 Skill。 |
孙割 LaTeX PDF
把一份 Markdown 生成一套或三套中文 PDF。生成过程只使用本 Skill 自带的脚本、字体和模板。
三套风格
| 参数 | 名称 | 适合内容 |
|---|
sun | 孙割原版 | 文字为主的小开本,保留 5×8 英寸、红黑封面和安静书页 |
journal | 界面志 | 图文、代码比例接近的中文技术长文,默认推荐 |
atlas | 屏幕图录 | 界面截图、宽表格和操作教程,横屏阅读 |
all | 三套全部生成 | 对比风格或一次交付多个版本 |
孙割原项目正文没有图片规则。本 Skill 的 sun 风格重新实现了正文图片与图注,并让宽图按小开本正文宽度完整缩放,同时保留原版视觉。
执行流程
- 确认输入 Markdown 的绝对路径
- 运行
scripts/doctor.sh 检查 Pandoc、XeLaTeX、ImageMagick、Poppler 和内置字体
- 根据用户指定选择风格;没有指定时使用
journal
- 调用
scripts/build.sh 生成 PDF
- 检查构建输出中的页数、中文数量、字体、图片数量、内容顺序和代码复制
- 运行
scripts/check_visual_layout.py 检查标题字号、标题孤行、图注位置、图注大小和低内容空白页
- 用
pdftoppm 渲染全部页面,实际查看封面、正文、代码、横图、竖图和最后一页
- 发现缺字、空白图、裁切、重叠或页眉遮挡时,修复模板并重新生成
生成命令
指定一种风格:
bash scripts/build.sh \
--input "/绝对路径/文章.md" \
--style journal \
--output "/绝对路径/输出/文章"
一次生成三套:
bash scripts/build.sh \
--input "/绝对路径/文章.md" \
--style all \
--output "/绝对路径/输出/文章"
覆盖标题或作者:
bash scripts/build.sh \
--input "/绝对路径/文章.md" \
--style all \
--output "/绝对路径/输出/文章" \
--title "新的标题" \
--author "作者名"
网络图片已经进入缓存后,可以增加 --offline 离线重建。需要目录时增加 --toc。
图片要求
支持以下写法:


![[assets/设计图.png]]
![[assets/设计图.png|图片说明]]
图片处理遵循这些规则:
- 网络图片先下载并缓存
- 本地图片复制为安全文件名,允许中文和空格路径
- SVG、WebP、GIF 转成 XeLaTeX 可以处理的格式
- 图片保持比例,受最大宽度和最大高度双重限制
- 孙割原版中的宽图按正文宽度完整缩放,标题、说明和图片保持连续
- 图片与图注按同一中心线排列,三套模板的图注保持一致的阅读大小
- 有说明时生成图注,空说明时不生成空图注
- 缺图、下载失败或转换失败时中止并指出原地址
- 禁止静默丢图
中文要求
- 正文使用思源宋体
- 标题和图注使用思源黑体
- 代码中的中文使用霞鹜文楷等宽
- 三种字体随 Skill 提供并附许可证
- PDF 必须嵌入字体,中文必须能够复制和搜索
- 长命令与网址必须自动换行
验收命令
生成后运行:
python3 scripts/verify_pdf.py \
--pdf "/绝对路径/文章-界面志.pdf" \
--minimum-images 1
完整回归测试:
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
交付前必须完成真实构建和可视检查。仅通过编译不代表完成。