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

6.9 KiB
Raw Blame History

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.json:

deno run -A main.ts generate pdf

选择自定义配置文件:

deno run -A main.ts --config ./config.release.json generate pdf

当配置中有多个 settings 时,可以只生成指定名称的 PDF 配置:

deno run -A main.ts --name mobile generate pdf

其他导出命令:

# 将每个配置的文章合并导出为 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 文件名格式为:

栏目顺序::栏目名::文章顺序::文章标题.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。