Use article link markers for PDF indexing

This commit is contained in:
Nobody committed 2026-11-17 16:26:01 +08:00
1 parent 09af3bd8c0
commit 33f15d9ce0
20 files changed
+1137 -293

No files matched your search

+120
View File
@@ -0,0 +1,120 @@
# build.js 开发指南
build.js 是完整 HTML 组装后的同步处理钩子,用于调整 DOM、样式或当前构建配置。
它由 `DocuBuilder.as_html_page()` 执行,具体实现见
[`pdf_builder/docu_builder.ts`](../pdf_builder/docu_builder.ts)。
![build.js 执行流程](diagrams/build-js-workflow.svg)
[编辑 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
```
@@ -0,0 +1 @@
<mxGraphModel adaptiveColors="auto" pageWidth="650" pageHeight="660"><root><mxCell id="0" /><mxCell id="1" parent="0" /><mxCell id="ir" value="HtmlDocument&lt;br&gt;章节 HTML 与布局" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="30" width="230" height="80" as="geometry" /></mxCell><mxCell id="assemble" value="DocuBuilder.as_html_page()&lt;br&gt;嵌入图片 · 组装 HTML · PDF 标记" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="160" width="230" height="80" as="geometry" /></mxCell><mxCell id="disabled" value="build_js_script = false&lt;br&gt;直接返回组装 HTML" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="360" y="160" width="230" height="80" as="geometry" /></mxCell><mxCell id="dom" value="启用脚本:读取文件并解析 DOM&lt;br&gt;注入 html / document / pages / cfg" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="290" width="230" height="80" as="geometry" /></mxCell><mxCell id="run" value="同步执行 build.js&lt;br&gt;修改 DOM 或显式 return 字符串" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="420" width="230" height="80" as="geometry" /></mxCell><mxCell id="serialize" value="默认序列化 documentElement&lt;br&gt;无 DOM 时回退 html" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="360" y="420" width="230" height="80" as="geometry" /></mxCell><mxCell id="output" value="继续导出 PDF / HTML / MD / TXT&lt;br&gt;EPUB 不经过此钩子" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="360" y="550" width="230" height="80" as="geometry" /></mxCell><mxCell id="e0" source="ir" target="assemble" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e1" source="assemble" target="disabled" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e2" source="assemble" target="dom" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e3" source="dom" target="run" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e4" source="run" target="serialize" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e5" source="serialize" target="output" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e6" source="disabled" target="output" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell></root></mxGraphModel>
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="650" height="660" viewBox="0 0 650 660" role="img"><title>build-js-workflow</title><metadata>&lt;mxGraphModel adaptiveColors=&quot;auto&quot; pageWidth=&quot;650&quot; pageHeight=&quot;660&quot;&gt;&lt;root&gt;&lt;mxCell id=&quot;0&quot; /&gt;&lt;mxCell id=&quot;1&quot; parent=&quot;0&quot; /&gt;&lt;mxCell id=&quot;ir&quot; value=&quot;HtmlDocument&amp;lt;br&amp;gt;章节 HTML 与布局&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;30&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;assemble&quot; value=&quot;DocuBuilder.as_html_page()&amp;lt;br&amp;gt;嵌入图片 · 组装 HTML · PDF 标记&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;160&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;disabled&quot; value=&quot;build_js_script = false&amp;lt;br&amp;gt;直接返回组装 HTML&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;360&quot; y=&quot;160&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;dom&quot; value=&quot;启用脚本:读取文件并解析 DOM&amp;lt;br&amp;gt;注入 html / document / pages / cfg&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;290&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;run&quot; value=&quot;同步执行 build.js&amp;lt;br&amp;gt;修改 DOM 或显式 return 字符串&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;420&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;serialize&quot; value=&quot;默认序列化 documentElement&amp;lt;br&amp;gt;无 DOM 时回退 html&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;360&quot; y=&quot;420&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;output&quot; value=&quot;继续导出 PDF / HTML / MD / TXT&amp;lt;br&amp;gt;EPUB 不经过此钩子&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;360&quot; y=&quot;550&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e0&quot; source=&quot;ir&quot; target=&quot;assemble&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e1&quot; source=&quot;assemble&quot; target=&quot;disabled&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e2&quot; source=&quot;assemble&quot; target=&quot;dom&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e3&quot; source=&quot;dom&quot; target=&quot;run&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e4&quot; source=&quot;run&quot; target=&quot;serialize&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e5&quot; source=&quot;serialize&quot; target=&quot;output&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e6&quot; source=&quot;disabled&quot; targLine truncated

After

Width:  |  Height:  |  Size: 8.9 KiB

@@ -0,0 +1 @@
<mxGraphModel adaptiveColors="auto" pageWidth="900" pageHeight="570"><root><mxCell id="0" /><mxCell id="1" parent="0" /><mxCell id="publication" value="PublicationInput&lt;br&gt;出版物 → 模板与 Markdown 渲染" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="30" width="230" height="80" as="geometry" /></mxCell><mxCell id="html" value="HtmlInput&lt;br&gt;已有 HTML 与章节元数据" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="330" y="30" width="230" height="80" as="geometry" /></mxCell><mxCell id="ir" value="HtmlDocument&lt;br&gt;章节 HTML · 元数据 · 资源 · 布局" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#bfe3d8;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="185" y="160" width="230" height="80" as="geometry" /></mxCell><mxCell id="text" value="TextOutput&lt;br&gt;组装 HTML · 图片嵌入 · build.js" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="300" width="230" height="80" as="geometry" /></mxCell><mxCell id="pdf" value="PdfOutput&lt;br&gt;组装 HTML · 标记 · build.js" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="330" y="300" width="230" height="80" as="geometry" /></mxCell><mxCell id="epub" value="EpubOutput&lt;br&gt;章节链接与资源打包" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="620" y="300" width="230" height="80" as="geometry" /></mxCell><mxCell id="textfile" value="HTML / Markdown / TXT&lt;br&gt;转换并写入文件" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="40" y="450" width="230" height="80" as="geometry" /></mxCell><mxCell id="pdffile" value="PDF&lt;br&gt;排版 → 索引 → 清理标记 → 后处理" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="330" y="450" width="230" height="80" as="geometry" /></mxCell><mxCell id="epubfile" value="EPUB&lt;br&gt;导航 · OPF · XHTML · ZIP" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;" vertex="1" parent="1"><mxGeometry x="620" y="450" width="230" height="80" as="geometry" /></mxCell><mxCell id="e0" source="publication" target="ir" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e1" source="html" target="ir" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e2" source="ir" target="text" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e3" source="ir" target="pdf" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e4" source="ir" target="epub" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e5" source="text" target="textfile" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e6" source="pdf" target="pdffile" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell><mxCell id="e7" source="epub" target="epubfile" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;"><mxGeometry relative="1" as="geometry" /></mxCell></root></mxGraphModel>
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="900" height="570" viewBox="0 0 900 570" role="img"><title>document-workflow</title><metadata>&lt;mxGraphModel adaptiveColors=&quot;auto&quot; pageWidth=&quot;900&quot; pageHeight=&quot;570&quot;&gt;&lt;root&gt;&lt;mxCell id=&quot;0&quot; /&gt;&lt;mxCell id=&quot;1&quot; parent=&quot;0&quot; /&gt;&lt;mxCell id=&quot;publication&quot; value=&quot;PublicationInput&amp;lt;br&amp;gt;出版物 → 模板与 Markdown 渲染&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;30&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;html&quot; value=&quot;HtmlInput&amp;lt;br&amp;gt;已有 HTML 与章节元数据&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#d9eee8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;330&quot; y=&quot;30&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;ir&quot; value=&quot;HtmlDocument&amp;lt;br&amp;gt;章节 HTML · 元数据 · 资源 · 布局&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#bfe3d8;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;185&quot; y=&quot;160&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;text&quot; value=&quot;TextOutput&amp;lt;br&amp;gt;组装 HTML · 图片嵌入 · build.js&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;300&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;pdf&quot; value=&quot;PdfOutput&amp;lt;br&amp;gt;组装 HTML · 标记 · build.js&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;330&quot; y=&quot;300&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;epub&quot; value=&quot;EpubOutput&amp;lt;br&amp;gt;章节链接与资源打包&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#e5e4f5;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;620&quot; y=&quot;300&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;textfile&quot; value=&quot;HTML / Markdown / TXT&amp;lt;br&amp;gt;转换并写入文件&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;40&quot; y=&quot;450&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;pdffile&quot; value=&quot;PDF&amp;lt;br&amp;gt;排版 → 索引 → 清理标记 → 后处理&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;330&quot; y=&quot;450&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;epubfile&quot; value=&quot;EPUB&amp;lt;br&amp;gt;导航 · OPF · XHTML · ZIP&quot; style=&quot;rounded=1;whiteSpace=wrap;html=1;fillColor=#fff0cf;strokeColor=#52716b;fontSize=14;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;&lt;mxGeometry x=&quot;620&quot; y=&quot;450&quot; width=&quot;230&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e0&quot; source=&quot;publication&quot; target=&quot;ir&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e1&quot; source=&quot;html&quot; target=&quot;ir&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e2&quot; source=&quot;ir&quot; target=&quot;text&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot; /&gt;&lt;/mxCell&gt;&lt;mxCell id=&quot;e3&quot; source=&quot;ir&quot; target=&quot;pdf&quot; edge=&quot;1&quot; parent=&quot;1&quot; style=&quot;edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;endArrow=block;&quot;&gt;&lt;mxGLine truncated

After

Width:  |  Height:  |  Size: 11 KiB

+179
View File
@@ -0,0 +1,179 @@
# 文档输入输出接口开发指南
所有格式以 `HtmlDocument` 为交换数据。输入端负责读取源内容、渲染模板和生成章节
HTML;输出端负责格式转换、资源处理与写入文件。公共入口是
[`document/mod.ts`](../document/mod.ts)。
![文档转换工作流程](diagrams/document-workflow.svg)
[编辑 draw.io 源图](diagrams/document-workflow.drawio)。SVG
是文档预览,修改图后应同步更新预览。
## 接口契约
```ts
interface DocumentInput {
read(): Promise<HtmlDocument>;
}
interface DocumentOutput {
write(document: HtmlDocument): Promise<OutputResult>;
}
interface OutputResult {
readonly path: string;
readonly mediaType: string;
}
```
`convertDocument(input, output)` 依次调用 `read()` 和 `write()`,返回写入结果。
错误直接向调用方传播;输出端应在 `finally` 中释放浏览器等资源。
接口没有流式读取、进度、取消或多文件返回协议;需要这些能力时应显式扩展契约。
## HTML 中间文档
完整类型见 [`document/types.ts`](../document/types.ts)。
| 字段 | 含义与约定 |
| --------------- | ------------------------------------------------------------- |
| `kind` | 固定为 `"html"` |
| `metadata` | `title`、`author`、`language`,可选 `identifier` |
| `baseDirectory` | 出版物绝对目录,供资源边界和路径解析使用 |
| `assetBase` | 共享资源目录;`PublicationInput` 会将其规范为绝对文件系统路径 |
| `chapters` | 已排序的章节数组;数组顺序就是输出顺序 |
| `layout` | `cover`、`styles`、`before`、`after` 四个 HTML 字符串 |
每个 `HtmlChapter` 包含唯一 `id`、`title`、`html`、绝对 `sourcePath`、文章
`index`,以及 `column: { name, index }`。`html` 是章节片段,保留原始资源引用,
不含 PDF 临时定位链接。`sourcePath` 为 EPUB 相对图片、章节链接提供解析基址,
即使输入并非 Markdown,也应提供有意义的来源路径。
`readonly` 是 TypeScript
的编译期约束,不会在运行时冻结对象。输出实现不得修改输入,
需要加工时建立局部字符串或复制数据。同一份文档可顺序交给多个输出端。 当前 PDF
标记编号仍按章节数组的顺序生成,尚未直接使用 `chapter.id`;标题索引仍以 标题为
Map 键,因此不同文章重名仍是现有索引的限制。
## 使用现有输入输出
以下示例放在 `tools/gp/` 下运行,`config` 和 `variables` 由调用方提供:
```ts
import {
convertDocument,
EpubOutput,
PublicationInput,
TextOutput,
} from "./document/mod.ts";
await convertDocument(
new PublicationInput(config, variables),
new TextOutput(config, "html"),
);
// 复用同一份 HTML,避免重复读取和渲染。
const document = await new PublicationInput(config, variables).read();
await new TextOutput(config, "md").write(document);
await new EpubOutput(config).write(document);
```
| 实现 | 处理方式 |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| `PublicationInput(config, variables)` | 使用 PFiles 排序并读取出版物;渲染模板和 Markdown,生成章节 HTML |
| `HtmlInput(document)` | 直接返回调用方传入的中间文档,不读取出版物 |
| `TextOutput(config, "html" / "md" / "txt", path?)` | 组装 HTML、嵌入本地章节图片、执行 build.js,按需转为 Markdown 或 TXT |
| `PdfOutput(config, options?)` | 浏览器排版、可选目录、清理定位标记、书签、可选 qpdf 和签名 |
| `EpubOutput(config, path?)` | 从章节 HTML 生成 XHTML,重写章节链接、打包本地资源并生成 EPUB 导航 |
PDF 配置类型为 `GPConfig`,扩展共享 `DocumentConfig`,包含 `pdf` 和
`playwright`;导出选项见 `PDFPipelineOptions`。CLI 的 PDF Worker
使用同一组接口。 旧 `DocuBuilder` / `EpubBuilder`
方法保留作兼容入口,新扩展优先使用公共接口。
输出路径可使用 `md.path`、`html.path`、`txt.path`、`epub.path` 或
`playwright.path`。HTML/TXT 未单独配置时从 `md.path` 或 `markdown_output`
派生,EPUB 也有兼容回退路径。转换器本身不选择路径,由输出适配器负责。
## 实现新的输入
例如接入数据库、远程接口或已有 HTML 文件时,实现 `read()` 并生成章节结构:
```ts
import type { DocumentInput, HtmlDocument } from "./document/mod.ts";
class ArticleHtmlInput implements DocumentInput {
constructor(private readonly root: string) {}
async read(): Promise<HtmlDocument> {
return {
kind: "html",
metadata: { title: "示例刊物", author: "编辑部", language: "zh-CN" },
baseDirectory: this.root,
assetBase: `${this.root}/assets`,
chapters: [{
id: "article-1",
title: "示例文章",
html: await Deno.readTextFile(`${this.root}/article.html`),
sourcePath: `${this.root}/article.html`,
index: 1,
column: { name: "示例专栏", index: 1 },
}],
layout: { cover: "", styles: "", before: "", after: "" },
};
}
}
```
`root` 应为绝对路径。输入负责确认章节顺序、ID
唯一性和元数据完整性;当前公共流水线 不提供运行时 schema
校验。模板变量应在输入阶段解析一次,不要让新输出再次解释源模板。
## 实现新的输出
新输出只依赖中间文档,不应重新读取出版物 Markdown:
```ts
import type {
DocumentOutput,
HtmlDocument,
OutputResult,
} from "./document/mod.ts";
class ChapterJsonOutput implements DocumentOutput {
constructor(private readonly path: string) {}
async write(document: HtmlDocument): Promise<OutputResult> {
await Deno.writeTextFile(
this.path,
JSON.stringify(document.chapters, null, 2),
);
return { path: this.path, mediaType: "application/json" };
}
}
```
此示例要求父目录已存在。生产实现应负责创建输出目录、处理资源路径、释放资源,
并将失败抛给调用方。如果需要 CLI 子命令,再接入 `cli/handlers.ts` 和
`cli/match.ts`; 无需调整其他输出实现。
## 资源与脚本边界
本地章节图片在文本和 PDF 组装阶段按共享资源基址嵌入;远程 URL 保持原样。 EPUB
根据章节来源路径和共享资源目录打包本地文件,远程资源当前不自动下载。
封面、字体和附加布局 HTML 不一定经过相同的章节图片嵌入逻辑。
EPUB 当前只消费章节和元数据,不复用 PDF 布局,也不执行 build.js。
PDF、HTML、Markdown、TXT 的脚本阶段详见 [build.js 开发指南](build-js.md)。
## 验证
在 `tools/gp/` 运行:
```sh
nix develop -c deno test -A document/document_test.ts
nix develop -c deno check document/mod.ts main.ts pdf_builder/worker.ts
```
新增输入应验证排序、变量与资源基址;新增输出应使用内存构造的 `HtmlDocument`
验证内容、路径、媒体类型以及输入未被修改。PDF / EPUB
的资源和索引变更还应运行相应测试。