# 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.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。普通读者链接(例如 ``)不会被缓存。 ```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" %} {{ headline | upper }} {% 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_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`。