Use article link markers for PDF indexing
This commit is contained in:
1 parent
09af3bd8c0
commit
33f15d9ce0
20 files changed
+1137
-293
No files matched your search
@@ -0,0 +1,120 @@
|
||||
# build.js 开发指南
|
||||
|
||||
build.js 是完整 HTML 组装后的同步处理钩子,用于调整 DOM、样式或当前构建配置。
|
||||
它由 `DocuBuilder.as_html_page()` 执行,具体实现见
|
||||
[`pdf_builder/docu_builder.ts`](../pdf_builder/docu_builder.ts)。
|
||||
|
||||

|
||||
|
||||
[编辑 draw.io 源图](diagrams/build-js-workflow.drawio)。
|
||||
|
||||
## 配置与执行时机
|
||||
|
||||
```toml
|
||||
[settings.journal]
|
||||
build_js_script = "../../templates/computer_template/build.js"
|
||||
```
|
||||
|
||||
路径相对于进程工作目录解析,通常为 `tools/gp`,不相对于模板目录。
|
||||
禁用时应显式配置:
|
||||
|
||||
```toml
|
||||
build_js_script = false
|
||||
```
|
||||
|
||||
当前判断是 `build_js_script != false`;省略字段不会自动禁用,而会尝试读取
|
||||
`undefined` 路径,因此不要省略。脚本在章节模板和 Markdown 已渲染、HTML
|
||||
布局已组装、 本地章节图片已处理之后执行;PDF 的临时定位链接也已加入。
|
||||
同一中间文档被多次导出时,每次 HTML 组装都会执行一次脚本。
|
||||
|
||||
| 格式 | 是否执行 | 后续步骤 |
|
||||
| -------- | -------- | ---------------------------------------- |
|
||||
| PDF | 是 | 浏览器分页、目录定位及合并、书签和后处理 |
|
||||
| HTML | 是 | 写入组装后的 HTML |
|
||||
| Markdown | 是 | 去除样式与脚本,再由 Turndown 转换 |
|
||||
| TXT | 是 | 转换 Markdown,再去除 Markdown 标记 |
|
||||
| EPUB | 否 | 独立从章节 HTML 打包,未接入该钩子 |
|
||||
|
||||
## 注入参数
|
||||
|
||||
脚本作为 `new Function("html", "document", "pages", "cfg", source)`
|
||||
的函数体执行。 这些变量由运行器注入,不需要也不能使用模块 `import` / `export`
|
||||
声明来获取:
|
||||
|
||||
| 名称 | 实际值 | 修改效果 |
|
||||
| ---------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
|
||||
| `html` | 全部片段以换行拼接的字符串 | 仅重新赋值不会改变已经解析的 DOM;需要显式返回新的字符串 |
|
||||
| `document` | `DOMParser.parseFromString(html, "text/html")` 结果,可能为 null | 修改 DOM 会反映到默认序列化结果 |
|
||||
| `pages` | 组装片段数组的浅复制 | 直接改数组不会自动更新 DOM;需要自行合并并返回 |
|
||||
| `cfg` | 当前 DocuBuilder 的配置对象 | 可修改本次组装所使用的配置,传播边界见下文 |
|
||||
|
||||
优先使用运行时的 DOMParser;不可用时动态加载 deno_dom。它是 HTML 解析器,
|
||||
不是浏览器页面:这里没有排版坐标、最终页码、浏览器事件或可依赖的 `window`。
|
||||
最终页码应由 PDF 链接标记定位。
|
||||
|
||||
## DOM 修改与返回值
|
||||
|
||||
通常直接修改 `document`,无需 return:
|
||||
|
||||
```js
|
||||
if (document) {
|
||||
for (const image of document.querySelectorAll("img")) {
|
||||
image.setAttribute("loading", "eager");
|
||||
}
|
||||
const style = document.createElement("style");
|
||||
style.textContent = ".passages { overflow-wrap: anywhere; }";
|
||||
document.head?.appendChild(style);
|
||||
}
|
||||
```
|
||||
|
||||
脚本末尾由运行器追加:
|
||||
|
||||
```js
|
||||
return document?.documentElement?.outerHTML ?? html;
|
||||
```
|
||||
|
||||
也可显式返回完整 HTML 字符串,覆盖默认序列化,例如:
|
||||
|
||||
```js
|
||||
return html.replaceAll("旧刊名", "新刊名");
|
||||
```
|
||||
|
||||
自行返回时要保留布局、章节容器和 PDF 定位链接;返回非字符串没有运行时校验,
|
||||
会使后续输出行为不可靠。修改 `pages` 后需要 `return pages.join("\n")` 才能生效,
|
||||
这会绕过 `document` 上的修改。默认的 `outerHTML` 不包含原始 doctype。
|
||||
|
||||
## 配置修改与索引
|
||||
|
||||
现有 printable 模板设置:
|
||||
|
||||
```js
|
||||
cfg.indexSearch = { mode: "sequential" };
|
||||
```
|
||||
|
||||
索引默认优先读取临时文章链接,只有缺失标记时才使用全文搜索配置。 搜索支持
|
||||
`single_jump`、`sequential`、`window`;窗口模式可指定
|
||||
`beforePages`、`afterPages`。
|
||||
|
||||
新输出适配器会为 DocuBuilder 浅复制配置。顶层赋值(如 `cfg.indexSearch = ...`)
|
||||
不会自动同步回流水线原始配置;嵌套对象仍可能共享引用。因此不要依赖脚本修改顶层
|
||||
配置来控制 PDF 后续索引或后处理。需要可靠配置时,在调用 `PdfOutput` 前设置
|
||||
实际传入的配置;现有 printable 的脚本赋值在新适配器路径下存在这一传播限制。
|
||||
脚本适合处理 HTML,转换流程配置应由调用方明确传入。
|
||||
|
||||
PDF 中 `https://wpep.invalid/article-start-编号` 是定位用链接:不要删除、重排为
|
||||
与章节数组不一致的顺序,或将文章标题整体替换到丢失这些链接。目录合并阶段会清除
|
||||
临时文章链接,保留正常读者链接。未添加目录的 PDF 当前不会经过该清理阶段。
|
||||
|
||||
## 运行规则与验证
|
||||
|
||||
脚本同步执行,不支持顶层 `await`;不要返回 Promise。该钩子不是沙箱:它在 Deno
|
||||
进程内执行,具有进程已获准的能力。异常会中断导出,不会静默跳过。
|
||||
|
||||
先用小规模出版物验证 DOM 和最终输出,再检查 PDF 分页。对 HTML 的结构变更应确认:
|
||||
专栏标题与首篇文章关系、后续文章分页、图片显示、文章定位链接,以及普通链接仍正确。
|
||||
修改共享行为后在 `tools/gp` 运行:
|
||||
|
||||
```sh
|
||||
nix develop -c deno test -A
|
||||
nix develop -c deno check main.ts document/mod.ts pdf_builder/worker.ts
|
||||
```
|
||||
Reference in new issue
Block a user