Files
wpep/tools/gp/README.md
T
2026-11-12 18:34:33 +08:00

428 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# GP 工农解放报刊物生成器
GP 是一个基于 Deno、Markdown 和 HTML 模板的刊物构建工具,可以将一组文章排版为
PDF,也可以导出合并后的 Markdown 或纯文本。PDF 支持自动生成目录、PDF 线性化和
OpenPGP 签名。
## 代码目录
`main.ts` 保留为命令入口,配置和输出路径仍相对于 `tools/gp` 工作目录解析。
各模块的测试与实现放在同一目录:
```text
tools/gp/
├── main.ts # 命令入口和配置加载
├── cli/ # 子命令分发与导出处理
├── publication/ # 出版物、专栏、文章读取及排序
├── template/ # 模板变量和模板渲染
├── mdit/ # Markdown 解析及插件
├── assets/ # 外部素材缓存
├── pdf_builder/ # 文档渲染、PDF 目录、流水线及 Worker
├── epub_builder/ # EPUB 章节和资源打包
└── sync/ # WebDAV 上传、同步及清理
```
## 工作流程
```text
文章 Markdown + HTML 模板
|
v
Markdown 转 HTML
|
v
Playwright + Chromium 生成 PDF
|
+------+------+
| |
目录 qpdf / OpenPGP
| |
+------+------+
v
输出文件
```
## 环境准备
### 使用 Nix Flake
项目提供 `flake.nix`,会提供 Deno、Node.js、qpdf、ripgrep;Linux 环境还会提供
Chromium 和 CJK 字体。
```bash
nix develop
```
开发环境会设置 `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`,并在能找到浏览器时自动设置
`CHROMIUM_PATH`。如果没有自动找到浏览器,请手动设置:
```bash
export CHROMIUM_PATH="$(command -v chromium)"
```
macOS 示例:
```bash
export CHROMIUM_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
```
### 手动安装
至少需要:
- [Deno](https://deno.com/)
- Chromium 或 Google Chrome
- qpdf(仅在启用 PDF 线性化时需要)
- GnuPG 密钥(仅在启用 PDF 签名时需要)
首次运行时,Deno 会根据 `deno.json` 下载依赖。
## 快速开始
默认读取当前目录的 `config.toml`:
```bash
deno run -A main.ts generate pdf
```
选择自定义配置文件(支持 TOML,仍兼容 `.json`):
```bash
deno run -A main.ts --config ./config.release.toml generate pdf
```
当配置中有多个 `settings` 时,可以只生成指定名称的 PDF 配置:
```bash
deno run -A main.ts --name mobile generate pdf
```
使用 `--from` 可临时覆盖配置中的
`journal.from_directory`。参数是现存目录时直接读取该目录;否则按刊物版本处理,从
`../../publications/<版本>` 读取:
```bash
deno run -A main.ts --from ./draft-publication generate pdf
deno run -A main.ts --from 26.0.0 generate md
```
其他导出命令:
```bash
# 将每个配置的文章合并导出为 Markdown
deno run -A main.ts generate md
# 导出为 HTML(图片直接内嵌,路径从 md.path 派生)
deno run -A main.ts generate html
# 根据 md.path 导出为纯文本(输出文件名中的 md 会替换为 txt)
deno run -A main.ts generate txt
# 按配置中的 publication 生成 EPUB 3,包含可点击目录和 EPUB 包内图片
deno run -A main.ts generate epub
```
Markdown 和 HTML 导出会将本地图片嵌入为 Base64 data URL。EPUB 不使用 data URL,
而是将图片作为 EPUB 包内资源保存并从章节引用,兼容 EPUB 阅读器的资源模型。
EPUB 默认使用 `md.path` 将扩展名替换为 `.epub`;也可在每个配置中设置
`[settings.epub]` 的 `path`、`title`、`author` 和 `language`。每篇文章会拆成独立章节,
EPUB 导航目录按出版物排序链接到各章节。
### 本地素材缓存
生成前可以用 `--local-cache`
缓存来源文件和模板中的外部素材。图片、字体、CSS、脚本等资源会下载到对应
publication 目录的 `.local-cache/`,URL 与本地文件的映射保存到
`.cache.toml`,原始素材引用会替换为本地 `file://` URL。普通读者链接(例如
`<a href="https://...">`)不会被缓存。
```bash
# 只缓存,不生成 PDF、Markdown 或文本
deno run -A main.ts --just-local-cache
# 缓存完成后继续生成 PDF
deno run -A main.ts --local-cache generate pdf
# 只处理指定配置
deno run -A main.ts --name printable --just-local-cache
```
重复运行会读取 `.cache.toml`,已存在的文件不会再次下载。`--just-local-cache`
可以和 `--name`、`--from` 一起使用;`--from` 指定的 publication
目录会成为缓存目录。
### WebDAV 同步
`upload` 上传 `assets` 和各 publication 的 `.local-cache`,`sync` 下载并覆盖到
对应本地位置,远端根目录默认为 `gp_upload`。WebDAV 地址和认证信息可通过命令行
传入,也可以写在当前工作目录的 `.env` 中:
```env
WEBDAV_URL=https://dav.example.com/remote.php/dav/files/user
WEBDAV_USERNAME=user
WEBDAV_PASSWORD=secret
WEBDAV_REMOTE_DIR=gp_upload
```
```bash
deno run -A main.ts upload --type all
deno run -A main.ts sync --type assets --url https://dav.example.com/dav --user user --password secret
deno run -A main.ts clean --type cache
```
`--type` 可选 `all`、`assets` 或 `cache`;`clean` 默认是 `all`,会删除本地
`assets`、`.local-cache` 和 `.cache.toml`。也可以用 `--remote-dir`
修改远端目录。
## 模板变量
HTML 模板和 Markdown 正文使用 Nunjucks 模板语法。最常用的变量写法是
`{{ title }}`,也支持 `{% if %}`、`{% for %}`、过滤器和 `{% set %}` 常量:
```markdown
{% set accent = "#b40000" %}
<span style="color: {{ accent }}">{{ headline | upper }}</span> {% if draft
%}(草稿){% endif %}
```
变量可以通过命令行传入。命令行值会自动识别为数字、布尔值或
`null`,并覆盖同名变量:
```bash
deno run -A main.ts --name mobile --vars-file ./vars.toml \
--headline "工人报" --draft false generate pdf
```
TOML 文件可以包含嵌套对象和数组:
```toml
headline = "工人报"
draft = false
[theme]
accent = "#b40000"
```
内置变量包括 `now`、`currentTime`、`currentDate`、`year`、`month`、`day`、
`weekday`、`timestamp`、`unixTimestamp`、`timezone`、`locale`、`platform`、
`architecture`、`runtime` 和 `config`。每篇文章还可以使用 `document.title`、
`document.index`、`document.file`,以及当前栏目的 `column.name` 和
`column.index`。配置文件顶层 `[vars]` 可定义全局模板变量,`journal.variables`
可定义单项构建的变量;单项变量、变量文件和命令行值依次覆盖全局变量。
```toml
asset_base = "../../assets"
[vars]
publication_name = "工农解放报"
draft = false
```
`asset_base` 指定浏览器解析 HTML 相对附件路径的基准目录或 `file://`
地址,默认值为 `../../assets`。例如 Markdown 中的 `![图片](pictures/rsf.png)`
会从该目录读取,不需要单独启动附件文件服务器。
目录搜索策略可以在模板的 `build.js` 中通过 `cfg.indexSearch` 调整。默认是
`single_jump`:逐页扫描,每页只读取一次页面文本,并匹配该页上所有尚未匹配的文章;未匹配到标题的页面不会中断后续查找:
```js
cfg.indexSearch = { mode: "single_jump" };
```
也可以显式使用 `sequential`,按文章顺序继续搜索,因此同一页可以匹配多篇文章:
```js
cfg.indexSearch = { mode: "sequential" };
```
如果 PDF 文本顺序不稳定,可以使用窗口搜索。它从上一条命中页附近搜索,页数均为
可选项:
```js
cfg.indexSearch = {
mode: "window",
beforePages: 1,
afterPages: 5,
};
```
`build.js` 在生成正文 HTML 时运行,因此对当前 `settings` 的 `cfg`
设置会传递给目录生成阶段。
PDF 生成时会根据配置执行以下步骤:生成 PDF、插入目录、使用 qpdf 线性化、使用
OpenPGP 签名。目录、qpdf 和签名是否执行分别由
`pdf.generate_index`、`pdf.use_qpdf.enabled` 和 `pdf.signing.enabled` 控制。
## 源文件组织
每个 `settings` 对象通过 `journal.from_directory`
指向一个刊物源目录。`journal.build_mode` 有两种模式。
### flat 模式
HTML 模板和 Markdown 文件放在同一个目录中。Markdown 文件名格式为:
```text
栏目顺序::栏目名::文章顺序::文章标题.md
```
顺序使用整数解析,并按栏目顺序、栏目内文章顺序排序。例如:
```text
26.4.0/
├── cover_page.html
├── style.html
├── fonts.html
├── 1::理论::1::发刊词.md
├── 1::理论::2::编辑部文章.md
├── 2::文艺::1::诗歌.md
└── end_page.html
```
### detached 模式
模板单独放在 `journal.template_directory`,文章按栏目分目录。栏目目录格式为:
```text
栏目顺序::栏目名/
```
目录中的 Markdown 文件格式为:
```text
文章顺序::文章标题.md
```
例如:
```text
templates/
├── cover_page.html
├── style.html
└── end_page.html
publications/
├── 1::理论/
│ ├── 1::发刊词.md
│ └── 2::编辑部文章.md
└── 2::文艺/
└── 1::诗歌.md
```
`cover_page.html`、`style.html` 和 `end_page.html` 是特殊模板文件;目录中的其他
`.html` 文件也会作为模板插入。Markdown 文件可以包含图片、链接及项目启用的
Markdown 扩展语法。
## 配置文件
配置文件是 JSON,不是 TOML。顶层必须包含 `settings` 数组,每个对象通常包含
`name`、`journal`、`pdf`、`playwright` 和 `md`:
```json
{
"settings": [
{
"name": "computer",
"journal": {
"from_directory": "./publications/26.4.0",
"build_mode": "flat",
"build_js_script": false
},
"pdf": {
"generate_index": true,
"use_qpdf": {
"enabled": true,
"options": "--linearize"
},
"signing": {
"enabled": false,
"key_path": "~/keys/signing-key.asc",
"output_path": "./outputs/computer.pdf.sig"
}
},
"playwright": {
"path": "./outputs/computer.pdf",
"format": "A4",
"printBackground": true,
"displayHeaderFooter": true,
"margin": {
"top": "20mm",
"bottom": "20mm"
}
},
"md": {
"path": "./outputs/computer.md"
}
}
]
}
```
主要字段:
| 字段 | 作用 |
| ---------------------------- | ------------------------------------------------- |
| `name` | 配置名称;用于 `--name` 选择 PDF 配置 |
| `journal.from_directory` | 文章源目录 |
| `journal.build_mode` | `flat` 或 `detached` |
| `journal.template_directory` | `detached` 模式的模板目录 |
| `journal.build_js_script` | 构建前执行的 JS 文件路径;设为 `false` 禁用 |
| `pdf.generate_index` | 是否生成并插入目录 |
| `pdf.use_qpdf.enabled` | 是否使用 qpdf 线性化 PDF |
| `pdf.signing` | OpenPGP 签名配置 |
| `playwright.path` | PDF 输出路径;其他 Playwright PDF 选项会原样传递 |
| `md.path` | Markdown 输出路径,也是 `generate txt` 的基础路径 |
路径相对于运行命令时的当前工作目录解析。`~/`
会在输入目录和签名密钥路径中展开为用户主目录。
## HTML 样式钩子
生成的 HTML 会为内容添加以下 class,模板可以据此覆盖样式:
- `global`:全局样式
- `c1`、`c2` 等:对应栏目样式
- `passages`:文章内容容器
- `c_title`:栏目标题
- `ch1`:栏目标题使用的自定义标签
`style.html` 应包含 CSS;字体声明可以放在单独的 HTML 模板中。Playwright 的
`headerTemplate` 和 `footerTemplate` 可使用 Chromium 提供的
`pageNumber`、`totalPages`、`title` 等占位符。
## 开发
```bash
# 运行测试
deno test -A
# 启动监听模式
deno task dev
# 检查类型和格式
deno check main.ts pdf_builder/pipeline.ts
deno fmt --check
```
## 常见问题
### 找不到 Chromium
确认 `CHROMIUM_PATH` 指向 Chromium 或 Chrome 的可执行文件,并检查文件可执行:
```bash
echo "$CHROMIUM_PATH"
test -x "$CHROMIUM_PATH"
```
### qpdf 失败
确认 qpdf 在 `PATH` 中,且 `pdf.use_qpdf.options` 是 qpdf
参数字符串。若不需要线性化,将 `enabled` 设为 `false`。
### 签名失败
确认 `key_path`
指向可读取的私钥文件,并在需要时通过运行环境提供签名密码。签名输出写入
`pdf.signing.output_path`。