tomevault-io 「排版不应该比写作更难。」—— 这套系统让你 30 秒出 8 张卡片。
核心能力
将 Markdown 文本自动转换为精美的小红书图文卡片，具体包括：
- Markdown 解析：H1/H2/段落/加粗/列表/表格/代码块 → HTML
- 分页引擎：按行号区间自动切分为多页卡片
- CSS 设计系统：米白底 + 思源宋体 + 1080px 宽度，开箱即用
- 截图自动化：Playwright 无头浏览器逐页截图为 PNG
工作流
Phase 0: 需求确认
收到用户请求后，确认以下信息：
| 信息 | 说明 | 默认值 |
|---|---|---|
| 源文件 | Markdown 正文路径 | 当前目录下的 .md 文件 |
| 文章标题 | 卡片第 1 页显示的大标题 | 从 Markdown H1 提取 |
| 作者名 | 作者区域显示名 | 用户自定义 |
| 日期 | 发布日期 | 今天 |
| 总页数 | 计划分几页 | 根据字数估算（每页 700-800 字） |
| 头像路径 | 作者头像图片路径 | avatar.jpg |
Phase 1: 分页规划
规则：
- 每页目标 700-800 字，页面高度约 2000px
- 最多 8 页正文（小红书上限 9 张图 = 1 封面 + 8 正文）
- 在自然断点处分页（段落之间、章节标题前）
- 第 1 页必须包含：标题 + 作者区域 + 开头 Hook
- 最后一页可以稍短
操作：
- 读取源 Markdown 文件
- 确定每页的行号范围
(start_line, end_line) - 记录到
PAGES配置数组
Phase 2: 生成 HTML
生成 xhs_pages.py 脚本，该脚本：
- 读取源 Markdown 文件
- 按
PAGES配置提取每页内容 - 将 Markdown 转换为 HTML（
md_to_html()函数） - 套用 CSS 设计系统模板
- 输出完整的多页 HTML 文件
CSS 设计系统核心参数：
| 参数 | 值 |
|---|---|
| 卡片宽度 | 1080px |
| 背景色 | #F9F9F6（米白） |
| 正文字体 | Noto Serif SC（思源宋体） |
| 正文字号 | 34px，行高 2.0 |
| H1 标题 | 56-60px，font-weight: 700 |
| H2 标题 | 44px，font-weight: 700 |
| 内边距 | 90px |
| 分割线色 | #E8E6D9 |
Markdown → HTML 支持的元素：
# H1→<h1>（仅第 1 页）## H2→<h2>- 段落 →
<p> **加粗**→<strong>*斜体*→<em>`代码`→<code>- 无序列表→<ul><li>1. 有序列表→<ul><li>- 表格 →
<table> ``` 代码块 ```→<pre><code>
Phase 3: 截图
运行 scripts/screenshot.py 自动截图：
# 固定高度 1080×1440（3:4 比例）
python scripts/screenshot.py
# 自适应高度（按内容实际高度）
python scripts/screenshot.py --auto-height
截图脚本自动处理：
- 自动查找
*_xhs_pages.html文件 - 等待 Google Fonts 加载（首页 3 秒）
- 清除浏览器扩展覆盖层（蓝色边框）
- 逐页截图输出到
output/目录
踩坑铁律
以下是 23+ 篇文章生产中积累的血泪教训。
| # | 铁律 | 原因 |
|---|---|---|
| 1 | 使用 headless 模式 | 非 headless 模式会渲染浏览器扩展的蓝色边框 |
| 2 | 首页等 3 秒 | Google Fonts（思源宋体）需要加载时间 |
| 3 | 不要用 python -c 内联命令 |
Windows 路径含单引号会被 PowerShell 吞掉 |
| 4 | 页脚放在 .content 内部 |
放在外面会被截图裁切 |
| 5 | 隐藏所有滚动条 | 需要 CSS 三重覆盖（overflow:hidden + -ms-overflow-style:none + ::-webkit-scrollbar） |
| 6 | 不要让 AI 直接输出 HTML | 中文 token 约为英文 2-3 倍，5000 字正文 HTML 会被截断。让 AI 写 Python 生成器脚本 |
| 7 | 超 8 页时增大每页字数 | 不要删内容，增加页面高度 |
文件引用
| 文件 | 用途 |
|---|---|
templates/xhs_card_template.html |
手动编辑时使用的 HTML 模板 |
scripts/screenshot.py |
通用截图脚本 |
examples/basic/xhs_pages.py |
生成器脚本参考实现 |
docs/design-system.md |
CSS 设计系统详细文档 |
docs/troubleshooting.md |
完整踩坑记录 |
诚实边界
- 本系统不会帮你写文章内容——它只管排版
- 本系统不会自动分页——你需要手动指定每页的行号范围
- 本系统不会处理图片插入——卡片目前为纯文字排版
- CSS 样式针对中文优化——英文排版可能需要微调字号和行高
- 需要本地安装 Python + Playwright，非零门槛
本 Skill 由 多少做点 BILL DO A BIT 创建 基于 23+ 篇正式文章的生产经验迭代
Source: BeardJohnJohn/md-poster — distributed by TomeVault.