create-asciidoc-multi-book-workspace 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.9.0 - 2026-11-01
+
+### Changed
+
+- Generated workspaces require Node.js 22 or later (`engines.node` is `>=22`). `asciidoctor-kroki` 2, the release line for Asciidoctor.js 4, requires it.
+- The HTML is rendered by Asciidoctor.js 4 (`@asciidoctor/core` `^4.1.1`), the same Asciidoctor `asciidoc-abundant-tree` reads the books with, and diagrams by `asciidoctor-kroki` `^2.0.0`. The runtime rewrites links to the heading IDs the projection read, and the copied source bundle promises the lines the HTML shows; with the HTML rendered by Asciidoctor.js 3 neither was guaranteed, and the two versions already read some includes differently (`include::f[lines=1_0]` is line 1 in version 4, line 10 in version 3). Links, anchors, the page map, and the copied source bundle of the sample books are unchanged. Visible differences come from Asciidoctor.js 4 itself: the generator meta tag and its default stylesheet, the class names of the table of contents in books with front or back matter, table column widths written as `width` attributes, and role classes written once instead of twice.
+- An include resolver may return a Promise; the HTML side waits for it as the reader data side does. A positional attribute left empty between others (`[a,,b]`) is `null` on both sides and no longer shifts the ones after it, so it is no longer forbidden.
+
+### Upgrading an existing workspace
+
+Make sure Node.js 22 or later runs the build. Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.9.0 tmp-books` and copy its `tools/adoc-books.mjs` over yours. In your `package.json`, set `"engines": { "node": ">=22" }`, `"@asciidoctor/core": "^4.1.1"`, and `"asciidoctor-kroki": "^2.0.0"`, then run `pnpm install`. Books need no change, and include resolvers that return their result directly keep working.
+
+## 0.8.0 - 2026-10-31
+
+### Changed
+
+- A link with no link text shows the name of its address. When the xref's address is the heading's title or one of its qualified addresses, the link shows it as written, its titles joined with an interpunct: `xref:红烧肉::火候[]` shows 红烧肉·火候 and `xref:家常菜::红烧肉::火候[]` shows all three titles, inside a book and across books. It used to show the last title alone (火候), so a book that referred to one of several 火候 wrote its address twice, once as the target and once as link text. An xref whose address is an ID still shows the heading's title, as Asciidoctor does for a section it resolves by ID. Link text the author writes is shown as written.
+- The structured writing conventions sample writes a qualified address once (《xref:红烧肉::火候[]》) and writes link text only where it says something other than the address's name. Its addressing chapter, print conventions, decision trees, and quick reference say so.
+
+### Upgrading an existing workspace
+
+Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.8.0 tmp-books` and copy its `tools/adoc-books.mjs` over yours. The `asciidoc-abundant-tree` range stays `^0.6.0`. Books need no change: link text written as the address's name, such as `xref:红烧肉::火候[红烧肉·火候]`, still shows the same, and can be removed.
+
 ## 0.7.0 - 2026-10-31
 
 ### Removed

package/dist/runtime/adoc-books.mjs

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import asciidoctorFactory from "@asciidoctor/core";
+import { convertFile as convertAsciiDocFile, Extensions, LoggerManager, MemoryLogger } from "@asciidoctor/core";
 import { parseAbundantTree, rdf12 } from "asciidoc-abundant-tree";
-const require = createRequire(import.meta.url);
 const DIAGRAM_BLOCK_PATTERN = /^\[(?:actdiag|blockdiag|bpmn|bytefield|c4plantuml|d2|dbml|ditaa|erd|excalidraw|graphviz|mermaid|nomnoml|nwdiag|packetdiag|pikchr|plantuml|rackdiag|seqdiag|svgbob|symbolator|umlet|vega|vegalite|wavedrom|structurizr|diagramsnet|wireviz)(?:,|\])/m;
 const HTML_ANCHOR_PATTERN = /\b(?:id|name)="([^"]+)"/g;
 const AAT_NAMESPACE = "https://micheng.dev/ns/asciidoc-abundant-tree#";
@@ -158,61 +156,50 @@ async function workspaceUsesDiagrams(rootDir, books) {
         sources.push(await combinedBookSource(book.bookDir));
     return sources.some((source) => DIAGRAM_BLOCK_PATTERN.test(source));
 }
-function createAsciidoctor(loadKroki) {
-    const asciidoctor = asciidoctorFactory();
+// 每次构建单独一个 registry，include 解析器与 Kroki 都登记在它上面：登记在全局会留在进程里，把上一个工作区的解析器
+// 带进下一个（DESIGN.adoc 的 Cheap Performance Rules）。
+async function createExtensionRegistry(config, loadKroki) {
+    const registry = Extensions.create();
+    registerIncludeResolvers(registry, config);
     if (loadKroki) {
         try {
-            require("asciidoctor-kroki").register(asciidoctor.Extensions);
+            (await import("asciidoctor-kroki")).register(registry);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             throw new Error(`current workspace contains diagram blocks, but asciidoctor-kroki could not be loaded: ${message}`);
         }
     }
-    return asciidoctor;
+    return registry;
 }
 // 书架登记的 include 解析器，在 HTML 这一侧由 Asciidoctor 的 include 处理器调用；阅读数据一侧由 aat 调用同一份，
-// 两侧读同一份行（DESIGN.adoc 的 Workspace Configuration）。每次构建单独一个 registry：Asciidoctor 3 的全局扩展
-// 在进程里一直留着，登记在全局会把上一个工作区的解析器带进下一个。
-function includeResolverRegistry(asciidoctor, config) {
+// 两侧读同一份行（DESIGN.adoc 的 Workspace Configuration）。
+function registerIncludeResolvers(registry, config) {
     if (config.includeResolvers.length === 0)
-        return asciidoctor.Extensions.create();
+        return;
     const claiming = (target) => config.includeResolvers.find((resolver) => target.startsWith(resolver.prefix));
-    // 以分组登记：registry 每绑定一个文档就重置一次，只有分组会重新登记。catalog 与各本书共用这一个 registry，
-    // 直接调 registry.includeProcessor 时只有第一个文档用得上；之后的文档把 include::前缀:… 当作 URI，
-    // 悄悄转成链接，不报任何消息。
-    return asciidoctor.Extensions.create(function () {
-        this.includeProcessor(function () {
-            this.handles((target) => claiming(target) !== undefined);
-            this.process((document, reader, target, attributes) => {
-                const resolver = claiming(target);
-                const cursor = reader.getCursor();
-                const sourcePath = cursor.getFile();
-                // 游标已越过 directive 这一行。
-                const location = `include::${target}[] in ${sourcePath}: line ${cursor.getLineNumber() - 1}`;
-                let resolution;
-                try {
-                    resolution = resolver.resolve({
-                        target: target.slice(resolver.prefix.length),
-                        attributes: includeAttributes(attributes),
-                        sourcePath
-                    });
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`include resolver '${resolver.prefix}' failed for ${location}: ${message}`, { cause: error });
-                }
-                if (typeof objectValue(resolution).then === "function") {
-                    // 不再等它：它若 reject，没人接住就成了进程级的未处理 rejection。
-                    Promise.resolve(resolution).catch(() => { });
-                    throw new Error(`include resolver '${resolver.prefix}' returned a Promise for ${location}; ` +
-                        "the HTML build runs on Asciidoctor.js 3, whose include processors are synchronous");
-                }
-                const { text, absolutePath, startLine } = checkedResolution(resolution, config.documentRoot, `include resolver '${resolver.prefix}'`, location);
-                // 显示用的路径照 Asciidoctor 自己 include 文件时的写法，相对文档的 base_dir。
-                const displayPath = path.relative(document.getBaseDir(), absolutePath).split(path.sep).join("/");
-                reader.pushInclude(text, absolutePath, displayPath, startLine, attributes);
-            });
+    // 直接登记在 registry 上：Asciidoctor.js 4 里 Extensions.create(分组函数) 登记的处理器从不被调用，include::前缀:…
+    // 被当作 URI 悄悄转成链接、不报任何消息；直接登记的处理器对 catalog 与各本书都有效。
+    registry.includeProcessor(function () {
+        this.handles((target) => claiming(target) !== undefined);
+        this.process(async (document, reader, target, attributes) => {
+            const resolver = claiming(target);
+            const cursor = reader.getCursor();
+            const sourcePath = cursor.getFile();
+            // 游标已越过 directive 这一行。
+            const location = `include::${target}[] in ${sourcePath}: line ${cursor.getLineNumber() - 1}`;
+            let resolution;
+            try {
+                resolution = await resolver.resolve({ target: target.slice(resolver.prefix.length), attributes, sourcePath });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`include resolver '${resolver.prefix}' failed for ${location}: ${message}`, { cause: error });
+            }
+            const { text, absolutePath, startLine } = checkedResolution(resolution, config.documentRoot, `include resolver '${resolver.prefix}'`, location);
+            // 显示用的路径照 Asciidoctor 自己 include 文件时的写法，相对文档的 base_dir。
+            const displayPath = path.relative(document.getBaseDir(), absolutePath).split(path.sep).join("/");
+            reader.pushInclude(text, absolutePath, displayPath, startLine, attributes);
         });
     });
 }
@@ -265,17 +252,6 @@ function shown(line) {
     const clipped = line.length > 60 ? `${line.slice(0, 60)}…` : line;
     return JSON.stringify(clipped).replaceAll("", "\\uFEFF");
 }
-// Asciidoctor.js 3 把位置属性放在 $positional 列表里；aat 跑在 4 上，位置属性以 "1"、"2" 为键。
-// 解析器只认后一种形状，同一个解析器才能服务两侧。留空的位置属性（[,x]）在 3 里是 undefined、在 4 里是 null，
-// 这里交 null；中间留空（[a,,b]）时 3 已把空位丢掉、编号与 4 不同，无从还原，规约写明位置属性不能留空。
-function includeAttributes(attributes) {
-    const { $positional, ...named } = attributes;
-    const positional = Array.isArray($positional) ? $positional : [];
-    return {
-        ...Object.fromEntries(positional.map((value, index) => [String(index + 1), value === undefined ? null : String(value)])),
-        ...Object.fromEntries(Object.entries(named).map(([name, value]) => [name, String(value)]))
-    };
-}
 function shouldFetchDiagrams() {
     const value = process.env[FETCH_DIAGRAMS_ENV];
     return value === "1" || value === "true";
@@ -319,14 +295,12 @@ function formatAsciidoctorMessage(message) {
     const text = messageText(message);
     return location ? `${severity}: ${location}: ${text}` : `${severity}: ${text}`;
 }
-function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir, attributes = {}) {
-    const loggerManager = asciidoctor.LoggerManager;
-    const defaultLogger = loggerManager.getLogger();
-    const memoryLogger = asciidoctor.MemoryLogger.create();
-    loggerManager.setLogger(memoryLogger);
-    let document;
+async function convertFile(extensionRegistry, input, outputFile, baseDir, attributes = {}) {
+    const defaultLogger = LoggerManager.getLogger();
+    const memoryLogger = MemoryLogger.create();
+    LoggerManager.setLogger(memoryLogger);
     try {
-        document = asciidoctor.convertFile(input, {
+        await convertAsciiDocFile(input, {
             safe: "unsafe",
             base_dir: baseDir,
             to_file: outputFile,
@@ -336,21 +310,20 @@ function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir,
         });
     }
     finally {
-        loggerManager.setLogger(defaultLogger);
+        LoggerManager.setLogger(defaultLogger);
     }
     const messages = memoryLogger.getMessages();
     if (messages.length > 0) {
         throw new Error(`AsciiDoc strict check failed for ${input}\n${messages.map(formatAsciidoctorMessage).join("\n")}`);
     }
-    return document;
 }
-async function buildHtml(rootDir, books, asciidoctor, extensionRegistry, useKroki, fetchDiagrams) {
+async function buildHtml(rootDir, books, extensionRegistry, useKroki, fetchDiagrams) {
     await mkdir(path.join(rootDir, "build", "html"), { recursive: true });
-    convertFile(asciidoctor, extensionRegistry, path.join(rootDir, "catalog.adoc"), path.join(rootDir, "build", "html", "catalog.html"), rootDir);
+    await convertFile(extensionRegistry, path.join(rootDir, "catalog.adoc"), path.join(rootDir, "build", "html", "catalog.html"), rootDir);
     await pruneStaleBookHtmlDirs(rootDir, books);
     for (const book of books) {
         await mkdir(book.htmlOutputDir, { recursive: true });
-        convertFile(asciidoctor, extensionRegistry, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
+        await convertFile(extensionRegistry, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
             ...(useKroki && fetchDiagrams ? { "kroki-fetch-diagram": "", "kroki-http-method": "post" } : {})
         });
     }
@@ -570,12 +543,16 @@ function bindReferences(config, document) {
     const sections = new Map(projection.nodeIndex.entries()
         .filter((entry) => entry.kind === "section")
         .map((entry) => [entry.iri.value, entry]));
-    const located = (iris) => [...iris].flatMap((iri) => {
+    // 地址的名字：选择器是这一节的标题或某个限定地址时，照写下的样子显示，各级标题之间用间隔号；是 ID（作者声明的或生成的）
+    // 时显示标题——ID 是给引用用的第二个地址，不是给读者看的名字。按图上是哪个标签判，不按字符串里有没有 :: 猜。
+    const located = (iris, selector) => [...iris].flatMap((iri) => {
         const entry = sections.get(iri);
         const id = entry?.node.ids?.[0];
         if (entry === undefined || id === undefined)
             return [];
-        return [{ id, title: entry.node.title ?? id }];
+        const node = { termType: "iri", value: iri };
+        const named = values(node, "headline").includes(selector) || values(node, "addressPath").includes(selector);
+        return [{ id, shown: named ? selector.split("::").join("·") : entry.node.title ?? id }];
     });
     // 别的书指过来的引用在这本书的 label space 里找：图上四个标签谓词的值，按整串相等找拥有者。
     const ownersByLabel = new Map();
@@ -588,7 +565,7 @@ function bindReferences(config, document) {
             ownersByLabel.set(triple.object.value, iris);
         }
     }
-    const owners = (selector) => located(ownersByLabel.get(selector) ?? []);
+    const owners = (selector) => located(ownersByLabel.get(selector) ?? [], selector);
     const headingsByFragment = new Map();
     const crossBook = [];
     // 指向整本书的 xref（没有片段）没有 targetSelector：没有可改写的片段。
@@ -600,7 +577,7 @@ function bindReferences(config, document) {
             crossBook.push({ document, fragment });
             continue;
         }
-        const found = located(values(edge, "targetHeading"));
+        const found = located(values(edge, "targetHeading"), fragment);
         if (found.length !== 1)
             continue;
         headingsByFragment.set(fragment, found[0]);
@@ -635,14 +612,14 @@ async function bindCrossBookReferences(book, references, bindingsByInput, anchor
         if (anchors.has(fragment))
             continue;
         const htmlPath = `${documentName}.html`;
-        const link = { href: `${htmlPath}#${heading.id}`, title: heading.title };
+        const link = { href: `${htmlPath}#${heading.id}`, shown: heading.shown };
         linksByHref.set(`${htmlPath}#${fragment}`, link);
         linksByHref.set(escapeHtmlAttribute(`${htmlPath}#${fragment}`), link);
     }
     return linksByHref;
 }
-// 在目标书里恰好对上一节、而目标书的 HTML 里没有这个片段的跨书链接，改成指向那一节的标题。Asciidoctor 对没写显示文字的跨书 xref
-// 显示文档路径；改写时换成标题。
+// 在目标书里恰好对上一节、而目标书的 HTML 里没有这个片段的跨书链接，改成指向那一节的标题。Asciidoctor 对没有显示文字的跨书 xref
+// 显示文档路径；改写时换成地址的名字。
 function rewriteCrossBookXrefs(html, linksByHref) {
     if (linksByHref.size === 0)
         return html;
@@ -650,12 +627,12 @@ function rewriteCrossBookXrefs(html, linksByHref) {
         const link = linksByHref.get(`${htmlPath}#${fragment}`) ?? linksByHref.get(`${htmlPath}#${decodeUrlFragment(fragment)}`);
         if (link === undefined)
             return whole;
-        const shown = text === htmlPath ? escapeHtmlAttribute(link.title) : text;
+        const shown = text === htmlPath ? escapeHtmlAttribute(link.shown) : text;
         return `<a href="${escapeHtmlAttribute(link.href)}"${rest}>${shown}</a>`;
     });
 }
 // Asciidoctor 把它解析不了的书内 xref 写成 <a href="#选择器">[选择器]</a>；aat 的投影里恰好对上一节的，改成指向那一节的标题，
-// 显示标题。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
+// 显示地址的名字。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
 function rewriteBoundXrefs(html, headingsByFragment) {
     if (headingsByFragment.size === 0)
         return html;
@@ -667,7 +644,7 @@ function rewriteBoundXrefs(html, headingsByFragment) {
         const heading = headingsByFragment.get(fragment) ?? headingsByFragment.get(decoded);
         if (heading === undefined)
             return whole;
-        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.title) : text;
+        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.shown) : text;
         return `<a href="#${escapeHtmlAttribute(heading.id)}"${rest}>${shown}</a>`;
     });
 }
@@ -1251,8 +1228,8 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const config = await loadRuntimeConfig(rootDir);
     const useKroki = await workspaceUsesDiagrams(rootDir, books);
     const fetchDiagrams = shouldFetchDiagrams();
-    const asciidoctor = createAsciidoctor(useKroki);
-    await buildHtml(rootDir, books, asciidoctor, includeResolverRegistry(asciidoctor, config), useKroki, fetchDiagrams);
+    const extensionRegistry = await createExtensionRegistry(config, useKroki);
+    await buildHtml(rootDir, books, extensionRegistry, useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
     await addHomeLinks(rootDir, books, config);
     await writeRootIndex(rootDir, config.rootIndex);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -49,15 +49,15 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22"
   },
   "devDependencies": {
-    "@asciidoctor/core": "^3.0.4",
-    "@types/node": "^24.10.1",
+    "@asciidoctor/core": "^4.1.1",
+    "@types/node": "^22.20.5",
     "asciidoc-abundant-tree": "link:../asciidoc-abundant-tree",
-    "asciidoctor-kroki": "^0.18.1",
-    "playwright": "^1.59.1",
-    "typescript": "^5.9.3"
+    "asciidoctor-kroki": "^2.0.0",
+    "playwright": "^1.64.1",
+    "typescript": "^7.0.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-decision-trees.adoc

@@ -91,8 +91,8 @@
    └─ 否：同一本书里经 include 拼起来的各个文件之间，xref 直接写标题。看第 2 步。
 
 2. 目标标题在它所在的书里与别的标题同名吗？
-   ├─ 是：把上级标题由近及远用 `::` 接在前面，补到候选只剩一个，如 `红烧肉::火候`，
-   │      并写上显示文本，各级之间用间隔号，如 `[红烧肉·火候]`。
+   ├─ 是：把上级标题由近及远用 `::` 接在前面，补到候选只剩一个，如 `红烧肉::火候`。
+   │      不必写显示文本：网页显示地址的名字，各级之间用间隔号，如《红烧肉·火候》。
    │      补到书名之下最高的一级仍分不开（同一个上级下同名）时，先把标题改得说得清这一节讲什么；
    │      改不了时，在那一节标题上方加 custom ID，xref 写这个 ID，
    │      并写上能分清是哪一节的显示文本。看第 3 步。

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-quick-reference.adoc

@@ -34,8 +34,8 @@
 |`[.dish]`
 |role：这一节在书里是什么。
 
-|`pass:[xref:红烧肉::火候[红烧肉·火候]]`
-|限定地址：几个标题同名时，把上级标题用 `::` 接在前面，指明其中一个；显示文本用间隔号。
+|`pass:[xref:红烧肉::火候[]]`
+|限定地址：几个标题同名时，把上级标题用 `::` 接在前面，指明其中一个；网页显示《红烧肉·火候》，各级之间用间隔号。
 
 |`[#…]`
 |custom ID：标题当不了地址时（同一个上级下同名，或标题里有 `#`、`::`）给它的第二个地址。
@@ -74,7 +74,7 @@
 写引用时，应符合下列规定：
 
 * 同一本书里经 include 拼起来的各个文件之间，引用直接写标题；
-* 几个标题同名时，引用写限定地址，例如 `pass:[xref:红烧肉::火候[红烧肉·火候]]`；
+* 几个标题同名时，引用写限定地址，例如 `pass:[xref:红烧肉::火候[]]`，不必再写显示文本；
 * 引用另一本书时，在书头定义一个文档属性，存那本书的入口路径（如 `:snack-book: ../02-home-snacks/book.adoc`），引用写成 `pass:[xref:{snack-book}#糖油饼[]]`，`#` 后面写那本书里的标题。
 
 反引号只改字体，反引号里的行内宏（如 xref）和属性引用照样会被替换。要原样展示它们，应把它们包在 `pass:[pass:[…]]` 里，外面再加反引号得到等宽字体。`= 书名`、`[.dish]` 这类块写法出现在行内时不会被当作结构，用反引号即可。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/020-heading-address-and-xref.adoc

@@ -55,17 +55,14 @@ Asciidoctor 还会从标题生成一个 ID，生成时去掉标点，同名的
 
 [source,asciidoc]
 ----
-糖色下锅以后怎样转火，见《xref:红烧肉::火候[红烧肉·火候]》。
+糖色下锅以后怎样转火，见《xref:红烧肉::火候[]》。
 ----
 
-`红烧肉::火候` 是这一节的限定地址。写限定地址时，应符合下列规定：
+`红烧肉::火候` 是这一节的限定地址。上级标题由近及远逐级补上，补到候选只剩一个为止。
 
-* 上级标题由近及远逐级补上，补到候选只剩一个为止；
-* 写上显示文本，各级标题之间用间隔号，例如 `红烧肉·火候`（见《xref:篇名用书名号[]》）。
+限定地址只写一遍，不必再写显示文本。链接没有显示文本时，网页上显示地址的名字，各级标题之间用间隔号（见《xref:篇名用书名号[]》），上面这句读者看到的是“见《红烧肉·火候》”。作者补上的上级标题，读者也要靠它分清是哪道菜的火候，所以显示时一级不少。想在链接上说别的话时，才写显示文本，例如 `pass:[xref:红烧肉::火候[那一锅的火候]]`，网页显示写下的这句。
 
-不写显示文本时，链接上只显示最后一级标题“火候”，读者看不出是哪道菜的。
-
-补一级不够时，再往上补一级。例如菜谱分了《家常菜》《宴客菜》两部，两部里都有《红烧肉》，引用家常菜里那一道的火候时，写 `pass:[xref:家常菜::红烧肉::火候[家常菜·红烧肉·火候]]`。补到书名之下最高的一级（分部的书是部，不分部的书是章），就是这一节完整的路径；书名全书只有一个，不必写。
+补一级不够时，再往上补一级。例如菜谱分了《家常菜》《宴客菜》两部，两部里都有《红烧肉》，引用家常菜里那一道的火候时，写 `pass:[xref:家常菜::红烧肉::火候[]]`，网页显示《家常菜·红烧肉·火候》。补到书名之下最高的一级（分部的书是部，不分部的书是章），就是这一节完整的路径；书名全书只有一个，不必写。
 
 同一个上级下有两个同名的标题时，完整的路径也分不开它们，例如糖醋排骨要炸两遍，《糖醋排骨》下写了两节《炸》。两节同名，多半是标题没有说清这一节讲什么。这时宜先改标题，例如改成《初炸》与《复炸》，改好以后，两节的标题各是各的地址。
 
@@ -74,7 +71,7 @@ Asciidoctor 还会从标题生成一个 ID，生成时去掉标点，同名的
 * 名字说清这一节讲什么，不写序号和位置词，例如不写 `炸-2`、`第二个炸`，因为序号和位置会随编排变化；
 * 名字不与书里的任何标题相同。例如给《卤味》下讲糖色的一节加了 `[#炒糖色]`，书里又有一节《炒糖色》，这个地址就对上两节；Asciidoctor 先按 ID 去找，网页上 `pass:[xref:炒糖色[]]` 落到加了 ID 的那一节，原来指《炒糖色》的引用便不声不响地指到了别处；
 * 同一个上级下同名的几节，要引用哪一节，就给哪一节加；只给其中一节加时，另一节的标题和限定地址仍然有两个候选；
-* 引用写上显示文本，写出能让读者分清是哪一节的说法。
+* 引用写上显示文本，写出能让读者分清是哪一节的说法：引用 custom ID 的链接显示的是标题，同名的几节显示得一样。
 
 custom ID 是同一个标题的第二个地址，不替代标题。作者是在要引用某一节时才发现标题当不了地址的，custom ID 也宜在那时再加，不必预先写下。
 

package/templates/default-workspace/books/07-structured-writing-conventions/parts/040-book-prose/040-print-conventions.adoc

@@ -18,7 +18,7 @@ ____
 做法见《红烧肉》。
 ____
 
-书名号标书名、卷名和篇名（4.15.3.1）；题目是一部特定的作品时用书名号，只是谈论的话题时才用引号（B.1.8）。书里的一节是这本书里的一篇，提到它时应加书名号。几篇并列时，书名号应紧挨着写，中间不加顿号（A.13）。提到的一节带链接时，xref 应写在书名号里面，例如 `《pass:[xref:红烧肉[]]》`，读者看到的是《红烧肉》，链接落在书名号里的标题上。书名和其中的篇名连着写时，中间用间隔号，例如《随园食单·须知单》；限定地址的显示文本也这样写，例如《红烧肉·火候》。
+书名号标书名、卷名和篇名（4.15.3.1）；题目是一部特定的作品时用书名号，只是谈论的话题时才用引号（B.1.8）。书里的一节是这本书里的一篇，提到它时应加书名号。几篇并列时，书名号应紧挨着写，中间不加顿号（A.13）。提到的一节带链接时，xref 应写在书名号里面，例如 `《pass:[xref:红烧肉[]]》`，读者看到的是《红烧肉》，链接落在书名号里的标题上。书名和其中的篇名连着写时，中间用间隔号，例如《随园食单·须知单》；链接没有显示文本时，网页把限定地址也这样显示，`《pass:[xref:红烧肉::火候[]]》` 读者看到的是《红烧肉·火候》。
 
 [.touchstone]
 === 中西文混排照规范

package/templates/default-workspace/package.json.template

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22"
   },
   "packageManager": "pnpm@10.33.0",
   "scripts": {
@@ -11,8 +11,8 @@
     "clean": "node tools/adoc-books.mjs clean"
   },
   "devDependencies": {
-    "@asciidoctor/core": "^3.0.4",
+    "@asciidoctor/core": "^4.1.1",
     "asciidoc-abundant-tree": "^0.6.0",
-    "asciidoctor-kroki": "^0.18.1"
+    "asciidoctor-kroki": "^2.0.0"
   }
 }