GP 工农解放报刊物生成器
GP 是一个基于 Deno、Markdown 和 HTML 模板的刊物构建工具,可以将一组文章排版为 PDF,也可以导出合并后的 Markdown 或纯文本。PDF 支持自动生成目录、PDF 线性化和 OpenPGP 签名。
工作流程
文章 Markdown + HTML 模板
|
v
Markdown 转 HTML
|
v
Playwright + Chromium 生成 PDF
|
+------+------+
| |
目录 qpdf / OpenPGP
| |
+------+------+
v
输出文件
环境准备
使用 Nix Flake
项目提供 flake.nix,会提供 Deno、Node.js、qpdf、ripgrep;Linux 环境还会提供
Chromium 和 CJK 字体。
nix develop
开发环境会设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1,并在能找到浏览器时自动设置
CHROMIUM_PATH。如果没有自动找到浏览器,请手动设置:
export CHROMIUM_PATH="$(command -v chromium)"
macOS 示例:
export CHROMIUM_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
手动安装
至少需要:
- Deno
- Chromium 或 Google Chrome
- qpdf(仅在启用 PDF 线性化时需要)
- GnuPG 密钥(仅在启用 PDF 签名时需要)
首次运行时,Deno 会根据 deno.json 下载依赖。
快速开始
默认读取当前目录的 config.toml:
deno run -A main.ts generate pdf
选择自定义配置文件(支持 TOML,仍兼容 .json):
deno run -A main.ts --config ./config.release.toml generate pdf
当配置中有多个 settings 时,可以只生成指定名称的 PDF 配置:
deno run -A main.ts --name mobile generate pdf
使用 --from 可临时覆盖配置中的
journal.from_directory。参数是现存目录时直接读取该目录;否则按刊物版本处理,从
../../publications/<版本> 读取:
deno run -A main.ts --from ./draft-publication generate pdf
deno run -A main.ts --from 26.0.0 generate md
其他导出命令:
# 将每个配置的文章合并导出为 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://...">)不会被缓存。
# 只缓存,不生成 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 中:
WEBDAV_URL=https://dav.example.com/remote.php/dav/files/user
WEBDAV_USERNAME=user
WEBDAV_PASSWORD=secret
WEBDAV_REMOTE_DIR=gp_upload
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 %} 常量:
{% set accent = "#b40000" %}
<span style="color: {{ accent }}">{{ headline | upper }}</span> {% if draft
%}(草稿){% endif %}
变量可以通过命令行传入。命令行值会自动识别为数字、布尔值或
null,并覆盖同名变量:
deno run -A main.ts --name mobile --vars-file ./vars.toml \
--headline "工人报" --draft false generate pdf
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
可定义单项构建的变量;单项变量、变量文件和命令行值依次覆盖全局变量。
asset_base = "../../assets"
[vars]
publication_name = "工农解放报"
draft = false
asset_base 指定浏览器解析 HTML 相对附件路径的基准目录或 file://
地址,默认值为 ../../assets。例如 Markdown 中的 
会从该目录读取,不需要单独启动附件文件服务器。
目录搜索策略可以在模板的 build.js 中通过 cfg.indexSearch 调整。默认是
single_jump:逐页扫描,每页只读取一次页面文本,并匹配该页上所有尚未匹配的文章;未匹配到标题的页面不会中断后续查找:
cfg.indexSearch = { mode: "single_jump" };
也可以显式使用 sequential,按文章顺序继续搜索,因此同一页可以匹配多篇文章:
cfg.indexSearch = { mode: "sequential" };
如果 PDF 文本顺序不稳定,可以使用窗口搜索。它从上一条命中页附近搜索,页数均为 可选项:
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 文件名格式为:
栏目顺序::栏目名::文章顺序::文章标题.md
顺序使用整数解析,并按栏目顺序、栏目内文章顺序排序。例如:
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,文章按栏目分目录。栏目目录格式为:
栏目顺序::栏目名/
目录中的 Markdown 文件格式为:
文章顺序::文章标题.md
例如:
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:
{
"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 等占位符。
开发
# 运行测试
deno test -A
# 启动监听模式
deno task dev
# 检查类型和格式
deno check main.ts pdf_pipeline.ts
deno fmt --check
常见问题
找不到 Chromium
确认 CHROMIUM_PATH 指向 Chromium 或 Chrome 的可执行文件,并检查文件可执行:
echo "$CHROMIUM_PATH"
test -x "$CHROMIUM_PATH"
qpdf 失败
确认 qpdf 在 PATH 中,且 pdf.use_qpdf.options 是 qpdf
参数字符串。若不需要线性化,将 enabled 设为 false。
签名失败
确认 key_path
指向可读取的私钥文件,并在需要时通过运行环境提供签名密码。签名输出写入
pdf.signing.output_path。