Files
wpep/tools/gp/README.md
T

15 KiB
Raw Blame History

GP 工农解放报刊物生成器

GP 是一个基于 Deno、Markdown 和 HTML 模板的刊物构建工具,可以将一组文章排版为 PDF,也可以导出合并后的 Markdown 或纯文本。PDF 支持自动生成目录、PDF 线性化和 OpenPGP 签名。

代码目录

开发文档:

文档转换统一使用 HTML 中间表示,公共接口从 document/mod.ts 导出:

DocumentInput.read() → HtmlDocument → DocumentOutput.write() → OutputResult

PublicationInput 读取出版物并渲染 Markdown 和模板变量;HtmlInput 接收已有的 HtmlDocument,无需读取 Markdown 文件。中间文档包含出版物元数据、按顺序排列的 HTML 章节(ID、标题、专栏、来源路径)、资源基址,以及封面、样式和前后附加内容。 章节 HTML 保留原始资源引用,不含 PDF 定位标记。

TextOutput 支持 HTML、Markdown、TXT;PdfOutput 负责浏览器排版、目录和后处理; EpubOutput 负责章节链接和资源打包。图片嵌入和格式专用标记在输出端处理。 现有 Builder 方法保留作兼容入口,新代码建议使用以下接口:

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 工作目录解析。 各模块的测试与实现放在同一目录:

tools/gp/
├── main.ts              # 命令入口和配置加载
├── cli/                 # 子命令分发与导出处理
├── publication/         # 出版物、专栏、文章读取及排序
├── template/            # 模板变量和模板渲染
├── mdit/                # Markdown 解析及插件
├── assets/              # 外部素材缓存
├── pdf_builder/         # 文档渲染、PDF 目录、流水线及 Worker
├── epub_builder/        # EPUB 章节和资源打包
└── sync/                # WebDAV 上传、同步及清理

工作流程

文章 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 中的 ![图片](pictures/rsf.png) 会从该目录读取,不需要单独启动附件文件服务器。

PDF 目录优先读取文章标题或首段上的唯一链接标记 https://wpep.invalid/article-start-编号,直接取得起始页码;标记齐全时不会提取或搜索正文。 合并目录时会删除这些临时链接注释及其 URL,保留标题文字和文章中的普通链接, 并将目录链接、PDF 书签指向插入目录后的对应页面。

只有缺少标记的文章才回退到标题全文搜索(例如处理旧 PDF)。回退搜索策略可以在模板的 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_builder/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。