# 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`。