Files
wpep/tools/gp/README.md
T
2026-10-26 12:35:16 +08:00

251 lines
6.9 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 签名。
## 工作流程
```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.json`:
```bash
deno run -A main.ts generate pdf
```
选择自定义配置文件:
```bash
deno run -A main.ts --config ./config.release.json generate pdf
```
当配置中有多个 `settings` 时,可以只生成指定名称的 PDF 配置:
```bash
deno run -A main.ts --name mobile generate pdf
```
其他导出命令:
```bash
# 将每个配置的文章合并导出为 Markdown
deno run -A main.ts generate md
# 根据 md.path 导出为纯文本(输出文件名中的 md 会替换为 txt)
deno run -A main.ts generate txt
```
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_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`。