474 lines
15 KiB
Markdown
474 lines
15 KiB
Markdown
# GP 工农解放报刊物生成器
|
||
|
||
GP 是一个基于 Deno、Markdown 和 HTML 模板的刊物构建工具,可以将一组文章排版为
|
||
PDF,也可以导出合并后的 Markdown 或纯文本。PDF 支持自动生成目录、PDF 线性化和
|
||
OpenPGP 签名。
|
||
|
||
## 代码目录
|
||
|
||
开发文档:
|
||
|
||
- [文档输入输出接口开发指南](docs/document-api.md):HTML 中间表示、接口契约与扩展示例。
|
||
- [build.js 开发指南](docs/build-js.md):执行时机、注入对象、DOM 修改和配置传播边界。
|
||
- [转换流程 draw.io 源图](docs/diagrams/document-workflow.drawio)
|
||
- [build.js 流程 draw.io 源图](docs/diagrams/build-js-workflow.drawio)
|
||
|
||
文档转换统一使用 HTML 中间表示,公共接口从 `document/mod.ts` 导出:
|
||
|
||
```text
|
||
DocumentInput.read() → HtmlDocument → DocumentOutput.write() → OutputResult
|
||
```
|
||
|
||
`PublicationInput` 读取出版物并渲染 Markdown 和模板变量;`HtmlInput` 接收已有的
|
||
`HtmlDocument`,无需读取 Markdown 文件。中间文档包含出版物元数据、按顺序排列的
|
||
HTML 章节(ID、标题、专栏、来源路径)、资源基址,以及封面、样式和前后附加内容。
|
||
章节 HTML 保留原始资源引用,不含 PDF 定位标记。
|
||
|
||
`TextOutput` 支持 HTML、Markdown、TXT;`PdfOutput`
|
||
负责浏览器排版、目录和后处理; `EpubOutput`
|
||
负责章节链接和资源打包。图片嵌入和格式专用标记在输出端处理。 现有 Builder
|
||
方法保留作兼容入口,新代码建议使用以下接口:
|
||
|
||
```ts
|
||
import {
|
||
convertDocument,
|
||
PublicationInput,
|
||
TextOutput,
|
||
} from "./document/mod.ts";
|
||
|
||
const input = new PublicationInput(config, variables);
|
||
const result = await convertDocument(input, new TextOutput(config, "html"));
|
||
console.log(result.path, result.mediaType);
|
||
```
|
||
|
||
同一份中间文档可交给多个输出端。新增输入实现
|
||
`DocumentInput.read()`,新增格式实现
|
||
`DocumentOutput.write()`,无需修改其他格式。输出接口不修改传入的中间文档。
|
||
HTML、TXT 可分别配置 `html.path`、`txt.path`;未配置时从 `md.path` 派生。
|
||
|
||
`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 中的 ``
|
||
会从该目录读取,不需要单独启动附件文件服务器。
|
||
|
||
PDF 目录优先读取文章标题或首段上的唯一链接标记
|
||
`https://wpep.invalid/article-start-编号`,直接取得起始页码;标记齐全时不会提取或搜索正文。
|
||
合并目录时会删除这些临时链接注释及其 URL,保留标题文字和文章中的普通链接,
|
||
并将目录链接、PDF 书签指向插入目录后的对应页面。
|
||
|
||
只有缺少标记的文章才回退到标题全文搜索(例如处理旧
|
||
PDF)。回退搜索策略可以在模板的 `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`。
|