create-asciidoc-multi-book-workspace 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.6.0 - 2026-10-31
+
+### Added
+
+- `pnpm run check` binds a qualified address: when several headings share a title, a book refers to one of them by writing the titles above it, joined with `::`, as in `xref:红烧肉::火候[]` or, across books, `xref:{dish-book}#红烧肉::火候[]`. The HTML link reaches that heading.
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.3.0`. Which xrefs exist and what their targets say are now read by Asciidoctor inside it, and the runtime no longer works around its gaps: xrefs inside passthroughs (`pass:[…]`, `+++…+++`, `$$…$$`, `` `+…+` ``) or escaped with `\` are not checked; `xref:` targets with spaces are bound and checked; `xref:#id[]` names `id`; an attribute reference in a target takes its value at the xref's position, where it used to take the value the book held after conversion; `xref:other#x[]` without `.adoc` names the document `other`, as Asciidoctor links it. The projection itself changed in 0.3.0 (fields are `field:<name>`, heading nodes are named by their address); tools that read it follow that release's changelog.
+- The structured writing conventions sample teaches qualified addresses for shared titles, written with link text that joins the titles with an interpunct (《红烧肉·火候》). Two headings that share a title under one parent are renamed so each title says what its section is (糖醋排骨's two 炸 become 初炸 and 复炸); a custom ID is the second address only for a title that cannot serve, with rules for naming it. After a rename, an author also searches the book for the old name in link text and prose, which the check does not report. The projection example shows heading nodes named by their address and the field predicate `field:难度`, and the fields chapter states that a field name in an attrlist uses only letters, digits, `_`, and `-`. `00-book-anatomy` and the `04-reference-manual` glossary say the same about custom IDs.
+
+### Upgrading an existing workspace
+
+A generated workspace owns its `tools/adoc-books.mjs`, and this release changes it. Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.6.0 tmp-books`, copy its `tools/adoc-books.mjs` over yours, set `"asciidoc-abundant-tree": "^0.3.0"` in your `package.json`, and run `pnpm install`. Books need no change; a heading that declares an ID only to tell it apart from others with the same title can drop the ID once its references use the qualified address.
+
+## 0.5.1 - 2026-10-23
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.2.6`. Releases 0.2.2–0.2.6 correct facts the reader pages are built from: edges with no source heading in included files, bibliography references, the Asciidoctor binding (`href`, reftext) of xrefs in descriptions and list items, and the span of description lists. The type of the attributes an include resolver receives now admits `null` (a blank positional attribute), as the runtime already passed it.
+
+### Upgrading an existing workspace
+
+Set `"asciidoc-abundant-tree": "^0.2.6"` in your `package.json` and run `pnpm install`. `tools/adoc-books.mjs` is unchanged in behavior; there is no need to copy it.
+
 ## 0.5.0 - 2026-10-21
 
 ### Added

package/dist/runtime/adoc-books.mjs

@@ -5,13 +5,16 @@ import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promi
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import asciidoctorFactory from "@asciidoctor/core";
-import { parseAbundantTree } from "asciidoc-abundant-tree";
+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 CATALOG_BOOK_XREF_PATTERN = /xref:books\/([^/\]]+)\/book\.adoc(?:#[^\[]+)?\[/g;
 const LOCAL_TARGET_PATTERN = /\b(href|src)="([^"]+)"/g;
 const HTML_ANCHOR_PATTERN = /\b(?:id|name)="([^"]+)"/g;
 const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+const AAT_NAMESPACE = "https://micheng.dev/ns/asciidoc-abundant-tree#";
+const HTML_FRAGMENT_LINK_PATTERN = /<a href="#([^"]*)"([^>]*)>([\s\S]*?)<\/a>/g;
+const HTML_DOCUMENT_LINK_PATTERN = /<a href="([^"#]+\.html)#([^"]*)"([^>]*)>([\s\S]*?)<\/a>/g;
 const HOME_MARKER = "data-multi-book-home";
 const CONTROLS_MARKER = "data-multi-book-controls";
 const FETCH_DIAGRAMS_ENV = "ADOC_BOOKS_FETCH_DIAGRAMS";
@@ -192,7 +195,6 @@ function includeResolverRegistry(asciidoctor, config) {
                 try {
                     resolution = resolver.resolve({
                         target: target.slice(resolver.prefix.length),
-                        // aat 一侧对留空的位置属性同样交 null，它的类型声明没有写出来。
                         attributes: includeAttributes(attributes),
                         sourcePath
                     });
@@ -323,8 +325,9 @@ function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir,
     const defaultLogger = loggerManager.getLogger();
     const memoryLogger = asciidoctor.MemoryLogger.create();
     loggerManager.setLogger(memoryLogger);
+    let document;
     try {
-        asciidoctor.convertFile(input, {
+        document = asciidoctor.convertFile(input, {
             safe: "unsafe",
             base_dir: baseDir,
             to_file: outputFile,
@@ -340,7 +343,9 @@ function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir,
     if (messages.length > 0) {
         throw new Error(`AsciiDoc strict check failed for ${input}\n${messages.map(formatAsciidoctorMessage).join("\n")}`);
     }
+    return document;
 }
+// 交回每本书转换后的 Asciidoctor 文档：书内与跨书 xref 的目标要用它展开属性引用（bindReferences）。
 async function buildHtml(rootDir, books, asciidoctor, 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);
@@ -465,14 +470,16 @@ function sourceBundleFromDocument(document) {
 // 解析失败就让构建失败，不退回只有封面的阅读页：退回时 include 越过 documentRoot 只剩一条 warning，
 // 构建照常成功，没有人发现阅读页坏了（DESIGN.adoc 的 Workspace Contract Checks）。
 async function buildReaderBookData(config, book) {
+    let parsed;
     let document;
     try {
-        document = await parseAbundantTree({
+        parsed = await parseAbundantTree({
             sourcePath: book.input,
             mode: "book-entry",
             documentRoot: config.documentRoot,
             includeResolvers: config.includeResolvers
         });
+        document = parsed;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -491,7 +498,9 @@ async function buildReaderBookData(config, book) {
     const sections = (Array.isArray(document.children) ? document.children : []).filter((child) => {
         return typeof child === "object" && child !== null && child.kind === "section";
     });
-    const frontmatterStyles = new Set(["abstract", "colophon", "dedication", "preface", "acknowledgments"]);
+    // abstract 不在其中：它是 article 的样式，book 里的 [abstract] 被 Asciidoctor 当作编号的一章，阅读器照它渲染的样子
+    // 当章节显示（docs/design/book-dual-reader-view.adoc 的 Page Map）。
+    const frontmatterStyles = new Set(["colophon", "dedication", "preface", "acknowledgments"]);
     const backmatterStyles = new Set(["appendix", "glossary", "bibliography", "index"]);
     const frontmatter = sections.filter((section) => section.level === 1 && frontmatterStyles.has(sectionStyle(section) ?? ""));
     if (frontmatter.length > 0) {
@@ -544,9 +553,143 @@ async function buildReaderBookData(config, book) {
     };
     return {
         pageMap,
-        sourceBundle: sourceBundleFromDocument(document)
+        sourceBundle: sourceBundleFromDocument(document),
+        references: bindReferences(config, parsed)
     };
 }
+// 书内 xref 指向谁，以 aat 的绑定为准（DESIGN.adoc 的 Reference Binding）：标题原文、限定地址、手写 ID、生成的 ID
+// 都在它的 label space 里，重名给出候选而不替人挑。哪些是 xref、目标写的是什么（透传与转义不算，属性已展开，
+// 指向别的文档的另记 targetDocument）也由 aat 里的 Asciidoctor 读出；这里只读投影里每条 xref 边的结果。
+function bindReferences(config, document) {
+    const projection = rdf12(document, { documentRoot: config.documentRoot });
+    const graph = projection.graph;
+    const values = (subject, name) => {
+        return graph.match({ subject, predicate: { termType: "iri", value: `${AAT_NAMESPACE}${name}` } })
+            .map((triple) => triple.object.termType === "triple" ? "" : triple.object.value);
+    };
+    const headings = new Map(projection.nodeIndex.entries()
+        .filter((entry) => entry.kind === "section")
+        .map((entry) => [entry.iri.value, entry]));
+    const located = (iris) => iris.flatMap((iri) => {
+        const entry = headings.get(iri);
+        const id = entry?.node.ids?.[0];
+        if (entry === undefined || id === undefined)
+            return [];
+        return [{ id, title: entry.node.title ?? id, relativePath: entry.relativePath ?? "", line: entry.sourceStartLine ?? entry.startLine }];
+    });
+    const owners = (selector) => {
+        return located(projection.labelCatalog.owners(selector).map((owner) => owner.value));
+    };
+    // 指向整本书的 xref（没有片段）没有 targetSelector，不在这里：它没有可绑定的东西，留给 HTML 本地资源检查。
+    const edges = graph.match({ predicate: { termType: "iri", value: `${AAT_NAMESPACE}targetSelector` } }).map((triple) => ({
+        iri: triple.subject,
+        selector: triple.object.termType === "triple" ? "" : triple.object.value,
+        document: values(triple.subject, "targetDocument")[0],
+        relativePath: values(triple.subject, "relativePath")[0] ?? "",
+        line: Number(values(triple.subject, "startLine")[0] ?? 0),
+        column: Number(values(triple.subject, "startColumn")[0] ?? 0)
+    })).sort((left, right) => left.relativePath.localeCompare(right.relativePath) || left.line - right.line || left.column - right.column);
+    const headingsByFragment = new Map();
+    const crossBook = [];
+    const issues = [];
+    for (const edge of edges) {
+        const where = `${edge.relativePath}:${edge.line} ${values(edge.iri, "raw")[0] ?? edge.selector}`;
+        if (edge.document !== undefined) {
+            crossBook.push({ where, document: edge.document, fragment: edge.selector });
+            continue;
+        }
+        const fragment = edge.selector;
+        const found = located([...values(edge.iri, "targetHeading"), ...values(edge.iri, "candidateHeading")]);
+        if (found.length === 1) {
+            const heading = { id: found[0].id, title: found[0].title };
+            headingsByFragment.set(fragment, heading);
+            headingsByFragment.set(escapeHtmlAttribute(fragment), heading);
+            continue;
+        }
+        if (found.length > 1) {
+            issues.push(issue("XREF_AMBIGUOUS", `${where} -> ${describeCandidates(found)}`));
+            continue;
+        }
+        issues.push(issue("XREF_UNRESOLVED", where));
+    }
+    return { headingsByFragment, crossBook, owners, issues };
+}
+function describeCandidates(headings) {
+    return [...headings]
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath) || left.line - right.line)
+        .map((heading) => `${heading.title} (${heading.relativePath}:${heading.line})`)
+        .join(", ");
+}
+// 跨书 xref 同样以 aat 的绑定为准，只是 label space 在目标书里（DESIGN.adoc 的 Reference Binding）。aat 不打开别的
+// 文档，工作区解析了每一本书，所以在这里绑定。路径按书目录解析：Asciidoctor 把它照写进 HTML，而 HTML 的输出目录
+// 与 books/ 下的书目录一一对应。指向的不是工作区里的书、或只指向整本书（没有片段）的，留给 HTML 本地资源检查。
+async function bindCrossBookReferences(book, references, bindingsByInput, anchorCache) {
+    const linksByHref = new Map();
+    const issues = [];
+    for (const xref of references.crossBook) {
+        const { fragment } = xref;
+        // Asciidoctor 把 xref:other#x[] 与 xref:other.adoc#x[] 都读成文档 other：去掉 .adoc、没有扩展名的照写，
+        // 再加 .html 写进 href。书的入口按 .adoc 登记，链接按 .html 改写，两边都从这个文档名出发。
+        const documentName = path.extname(xref.document) === ".adoc" ? xref.document.slice(0, -".adoc".length) : xref.document;
+        const target = bindingsByInput.get(path.resolve(book.bookDir, `${documentName}.adoc`));
+        if (fragment === "" || target === undefined)
+            continue;
+        const found = target.references.owners(fragment);
+        if (found.length === 0) {
+            issues.push(issue("XREF_UNRESOLVED", `${xref.where} -> ${target.book.bookId}`));
+            continue;
+        }
+        if (found.length > 1) {
+            issues.push(issue("XREF_AMBIGUOUS", `${xref.where} -> ${target.book.bookId}: ${describeCandidates(found)}`));
+            continue;
+        }
+        const heading = found[0];
+        // 指向本书自己的 book.adoc：Asciidoctor 把它当书内引用，写成 #片段。
+        if (target.book.bookId === book.bookId) {
+            references.headingsByFragment.set(fragment, heading);
+            references.headingsByFragment.set(escapeHtmlAttribute(fragment), heading);
+            continue;
+        }
+        const anchors = await anchorsForHtmlFile(path.join(target.book.htmlOutputDir, "book.html"), anchorCache);
+        if (anchors.has(fragment))
+            continue;
+        const htmlPath = `${documentName}.html`;
+        const link = { href: `${htmlPath}#${heading.id}`, title: heading.title };
+        linksByHref.set(`${htmlPath}#${fragment}`, link);
+        linksByHref.set(escapeHtmlAttribute(`${htmlPath}#${fragment}`), link);
+    }
+    return { linksByHref, issues };
+}
+// 绑定上、而目标书的 HTML 里没有这个片段的跨书链接，改成指向绑定的标题。Asciidoctor 对没写显示文字的跨书 xref
+// 显示文档路径；改写时换成标题。
+function rewriteCrossBookXrefs(html, linksByHref) {
+    if (linksByHref.size === 0)
+        return html;
+    return html.replace(HTML_DOCUMENT_LINK_PATTERN, (whole, htmlPath, fragment, rest, text) => {
+        const link = linksByHref.get(`${htmlPath}#${fragment}`) ?? linksByHref.get(`${htmlPath}#${decodeUrlFragment(fragment)}`);
+        if (link === undefined)
+            return whole;
+        const shown = text === htmlPath ? escapeHtmlAttribute(link.title) : text;
+        return `<a href="${escapeHtmlAttribute(link.href)}"${rest}>${shown}</a>`;
+    });
+}
+// Asciidoctor 把它解析不了的书内 xref 写成 <a href="#选择器">[选择器]</a>；aat 绑定上的，改成指向绑定的标题，
+// 显示标题。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
+function rewriteBoundXrefs(html, headingsByFragment) {
+    if (headingsByFragment.size === 0)
+        return html;
+    const anchors = htmlAnchors(html);
+    return html.replace(HTML_FRAGMENT_LINK_PATTERN, (whole, fragment, rest, text) => {
+        const decoded = decodeUrlFragment(fragment);
+        if (anchors.has(fragment) || anchors.has(decoded))
+            return whole;
+        const heading = headingsByFragment.get(fragment) ?? headingsByFragment.get(decoded);
+        if (heading === undefined)
+            return whole;
+        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.title) : text;
+        return `<a href="#${escapeHtmlAttribute(heading.id)}"${rest}>${shown}</a>`;
+    });
+}
 function readerStyles() {
     return `
 .multi-book-reader-toggle {
@@ -1062,13 +1205,24 @@ ${readerStyles()}
 }
 async function addHomeLinks(rootDir, books, config) {
     const catalog = path.join(rootDir, "build", "html", "catalog.html");
+    // 跨书 xref 在目标书的 label space 里绑定，所以先把每一本书都解析完。
+    const readerData = new Map();
+    for (const book of books) {
+        readerData.set(book.bookId, await buildReaderBookData(config, book));
+    }
+    const bindingsByInput = new Map(books.map((book) => [book.input, { book, references: readerData.get(book.bookId).references }]));
+    const anchorCache = new Map();
+    const issues = [];
     for (const book of books) {
         const htmlFile = path.join(book.htmlOutputDir, "book.html");
-        const html = await readFile(htmlFile, "utf8");
         const href = path.relative(path.dirname(htmlFile), catalog);
-        const readerData = await buildReaderBookData(config, book);
-        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
+        const data = readerData.get(book.bookId);
+        const crossBook = await bindCrossBookReferences(book, data.references, bindingsByInput, anchorCache);
+        issues.push(...data.references.issues, ...crossBook.issues);
+        const html = rewriteCrossBookXrefs(rewriteBoundXrefs(await readFile(htmlFile, "utf8"), data.references.headingsByFragment), crossBook.linksByHref);
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, data.sourceBundle, data.pageMap, book.bookId), "utf8");
     }
+    return issues;
 }
 async function writeRootIndex(rootDir, rootIndex) {
     const outputDir = path.join(rootDir, "build", "html");
@@ -1096,9 +1250,8 @@ function extractCatalogBookIds(catalogSource) {
 function issue(code, detail) {
     return { code, detail };
 }
-// xref 的目标与锚点不在这里查：Asciidoctor 把它们写成 HTML 里的链接与 ID，missingLocalResources 在生成的 HTML 上
-// 核对（DESIGN.adoc 的 Workspace Contract Checks）。ID 有 [#id]、[.role#id]、[[id]]、[id=id] 与标题生成等写法，
-// 只有 Asciidoctor 认得全。
+// xref 不在这里查：书内与跨书的引用以 aat 的绑定为准（bindReferences、bindCrossBookReferences），不存在的书与其余
+// 锚点由 missingLocalResources 在生成的 HTML 上核对（DESIGN.adoc 的 Workspace Contract Checks 与 Reference Binding）。
 async function workspaceContractIssues(rootDir, books) {
     const issues = [];
     const catalogSource = await readIfExists(path.join(rootDir, "catalog.adoc"));
@@ -1205,8 +1358,9 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const asciidoctor = createAsciidoctor(useKroki);
     await buildHtml(rootDir, books, asciidoctor, includeResolverRegistry(asciidoctor, config), useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
-    await addHomeLinks(rootDir, books, config);
+    const referenceIssues = await addHomeLinks(rootDir, books, config);
     await writeRootIndex(rootDir, config.rootIndex);
+    await assertNoIssues("reference binding check", referenceIssues);
     await assertNoIssues("HTML local resource check", await missingLocalResources(rootDir));
     await assertNoIssues("workspace contract check", await workspaceContractIssues(rootDir, books));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
     "@types/node": "^24.10.1",
-    "asciidoc-abundant-tree": "^0.2.1",
+    "asciidoc-abundant-tree": "^0.3.0",
     "asciidoctor-kroki": "^0.18.1",
     "playwright": "^1.59.1",
     "typescript": "^5.9.3"

package/templates/default-workspace/books/00-book-anatomy/backmatter/{appendix-a.adoc → appendix-structure-reference.adoc}

@@ -1,4 +1,4 @@
-= 附录 A：结构速查
+= 结构速查
 
 [cols="1,2", options="header"]
 |===

package/templates/default-workspace/books/00-book-anatomy/book.adoc

@@ -5,16 +5,16 @@ v0.1, 2026-05
 :toc: left
 :toclevels: 3
 :sectnums:
+:partnums:
+:part-signifier: Part
 :icons: font
 :experimental:
+:appendix-caption: 附录
 :idprefix:
 :idseparator: -
 
 include::../../shared/attributes.adoc[]
 
-[abstract]
-include::frontmatter/abstract.adoc[]
-
 [colophon]
 include::frontmatter/colophon.adoc[]
 
@@ -27,24 +27,24 @@ include::frontmatter/preface.adoc[]
 [acknowledgments]
 include::frontmatter/acknowledgments.adoc[]
 
-= 第一部：前置结构
+= 前置结构
 
 [partintro]
-include::parts/01-front-structure/_partintro.adoc[]
+include::parts/010-front-structure/_partintro.adoc[]
 
-include::parts/01-front-structure/01-frontmatter-map.adoc[]
+include::parts/010-front-structure/010-frontmatter-map.adoc[]
 
-= 第二部：正文结构
+= 正文结构
 
 [partintro]
-include::parts/02-body-structure/_partintro.adoc[]
+include::parts/020-body-structure/_partintro.adoc[]
 
-include::parts/02-body-structure/01-body-map.adoc[]
+include::parts/020-body-structure/010-body-map.adoc[]
 
-include::parts/02-body-structure/02-inline-structure.adoc[]
+include::parts/020-body-structure/020-inline-structure.adoc[]
 
 [appendix]
-include::backmatter/appendix-a.adoc[]
+include::backmatter/appendix-structure-reference.adoc[]
 
 [glossary]
 include::backmatter/glossary.adoc[]

package/templates/default-workspace/books/00-book-anatomy/parts/{01-front-structure/01-frontmatter-map.adoc → 010-front-structure/010-frontmatter-map.adoc}

@@ -1,4 +1,3 @@
-[#frontmatter-map]
 == 前置内容地图
 
 前置内容用于建立读者进入正文之前需要知道的说明、来源和阅读位置。
@@ -9,9 +8,6 @@
 |===
 |结构 |职责
 
-|`[abstract]`
-|说明整本书覆盖什么。
-
 |`[colophon]`
 |记录版本、出版或来源信息。
 
@@ -24,3 +20,5 @@
 |`[acknowledgments]`
 |放置致谢。
 |===
+
+书没有摘要。`[abstract]` 是 article 的 section style：摘要概述一篇文章，书的前置内容里没有这一项。在 book 里写 `[abstract]`，Asciidoctor 会把那一节当作普通的一章编号，它后面每一章的编号都跟着多一。一本书覆盖什么、怎样读，写在前言里。

package/templates/default-workspace/books/00-book-anatomy/parts/010-front-structure/_partintro.adoc

@@ -0,0 +1 @@
+本部展示一本书进入正文之前的结构位置。版本说明、献辞、前言和致谢都属于书籍前置内容。

package/templates/default-workspace/books/00-book-anatomy/parts/{02-body-structure/01-body-map.adoc → 020-body-structure/010-body-map.adoc}

@@ -1,4 +1,3 @@
-[#body-map]
 == 正文结构地图
 
 part 是 book doctype 中 document title 之后的 level 0 section。level 1 section 通常形成 chapter；multipart book 中 chapter 位于 part 下，普通 book 中 chapter 可以直接位于 book 下。

package/templates/default-workspace/books/00-book-anatomy/parts/020-body-structure/020-inline-structure.adoc

@@ -0,0 +1,31 @@
+== 内联结构标记
+
+内联结构标记给正文中的术语、路径和索引入口标出它们的身份，并写出正文对别的章节的引用。它不改变 book 的章节层级，但会提高正文片段的可维护性和可检索性。
+
+[cols="1,2", options="header"]
+|===
+|写法 |结构作用
+
+|`xref:正文结构地图[]`
+|按标题引用同一本书里的一节：标题就是这一节的地址。
+
+|`[#id]`
+|custom ID：给标题再加一个地址。同名的标题先写上级标题、以 `::` 隔开来引用（`pass:[xref:上级标题::本节标题[]]`）；同一个上级下也同名，或标题里有 `#`、`::` 时才写。
+
+|`indexterm2:[term]`
+|把正文中已经出现的词作为可见索引词。
+
+|`indexterm:[term, detail]`
+|正文没有出现该词时，补充隐藏索引入口。
+
+|`[.term]#inline role#`
+|给术语片段提供语义身份。
+
+|`[.path]` + monospace path
+|给路径文本提供语义身份。
+
+|`{series-name}`
+|引用共享属性，减少多处重复文本。
+|===
+
+语义 inline role 提供结构身份；具体视觉效果取决于输出样式。本书使用 [.term]#inline role# 标记术语片段，使用 [.path]`parts/020-body-structure/` 标记路径片段。

package/templates/default-workspace/books/01-starter-book/backmatter/{appendix-a.adoc → appendix-minimal-files.adoc}

@@ -1,4 +1,4 @@
-== 附录 A：最小文件清单
+== 最小文件清单
 
 普通新书通常需要：
 

package/templates/default-workspace/books/01-starter-book/book.adoc

@@ -7,6 +7,7 @@ v0.1, 2026-05
 :sectnums:
 :icons: font
 :experimental:
+:appendix-caption: 附录
 :idprefix:
 :idseparator: -
 
@@ -15,12 +16,12 @@ include::../../shared/attributes.adoc[]
 [preface]
 include::frontmatter/preface.adoc[]
 
-include::chapters/01-opening.adoc[]
+include::chapters/010-opening.adoc[]
 
-include::chapters/02-main-flow.adoc[]
+include::chapters/020-main-flow.adoc[]
 
 [appendix]
-include::backmatter/appendix-a.adoc[]
+include::backmatter/appendix-minimal-files.adoc[]
 
 [bibliography]
 include::backmatter/bibliography.adoc[]

package/templates/default-workspace/books/01-starter-book/chapters/{01-opening.adoc → 010-opening.adoc}

@@ -1,4 +1,3 @@
-[#starter-book-boundary]
 == 单书边界
 
 一本普通书由自己的 `book.adoc` 定义边界。入口文件负责书名、属性、章节顺序、前置内容和后置内容。

package/templates/default-workspace/books/02-multipart-monograph/backmatter/appendix-part-reference.adoc

@@ -0,0 +1,5 @@
+= part 速查
+
+* `= 问题世界`：同一本 book 内部的 part。标题只写语义名；`Part I`、`Part II` 这样的序号由书头的 `:partnums:` 生成，不写进标题。
+* `[partintro]`：part 开头的说明块。
+* `== 章标题`：part 下的 chapter。

package/templates/default-workspace/books/02-multipart-monograph/book.adoc

@@ -5,33 +5,36 @@ v0.1, 2026-05
 :toc: left
 :toclevels: 3
 :sectnums:
+:partnums:
+:part-signifier: Part
 :icons: font
 :experimental:
+:appendix-caption: 附录
 :idprefix:
 :idseparator: -
 
 include::../../shared/attributes.adoc[]
 
-= 第一部：问题世界
+= 问题世界
 
 [partintro]
-include::parts/01-domain/_partintro.adoc[]
+include::parts/010-domain/_partintro.adoc[]
 
-include::parts/01-domain/01-problem-world.adoc[]
+include::parts/010-domain/010-problem-world.adoc[]
 
-include::parts/01-domain/02-boundary.adoc[]
+include::parts/010-domain/020-boundary.adoc[]
 
-= 第二部：书籍规约
+= 书籍规约
 
 [partintro]
-include::parts/02-specification/_partintro.adoc[]
+include::parts/020-specification/_partintro.adoc[]
 
-include::parts/02-specification/01-book-contract.adoc[]
+include::parts/020-specification/010-book-contract.adoc[]
 
-include::parts/02-specification/02-verification.adoc[]
+include::parts/020-specification/020-verification.adoc[]
 
 [appendix]
-include::backmatter/appendix-a.adoc[]
+include::backmatter/appendix-part-reference.adoc[]
 
 [bibliography]
 include::backmatter/bibliography.adoc[]

package/templates/default-workspace/books/02-multipart-monograph/parts/{01-domain/01-problem-world.adoc → 010-domain/010-problem-world.adoc}

@@ -1,4 +1,3 @@
-[#multipart-book-boundary]
 == 长书的问题世界
 
 长书仍然只有一个书名、一个入口和一个连续的阅读产物。第一部、第二部只是同一本书内部的大分部。

package/templates/default-workspace/books/02-multipart-monograph/parts/{01-domain → 010-domain}/_partintro.adoc

@@ -1,2 +1 @@
-[#partintro-example]
 本部说明为什么同一本长书需要 part。part intro 为该部提供进入正文之前的过渡说明。

package/templates/default-workspace/books/03-technical-book-workflow/book.adoc

@@ -15,11 +15,11 @@ include::../../shared/attributes.adoc[]
 [preface]
 include::frontmatter/preface.adoc[]
 
-include::chapters/01-build-flow.adoc[]
+include::chapters/010-build-flow.adoc[]
 
-include::chapters/02-diagrams.adoc[]
+include::chapters/020-diagrams.adoc[]
 
-include::chapters/03-code-includes.adoc[]
+include::chapters/030-code-includes.adoc[]
 
 [bibliography]
 include::backmatter/bibliography.adoc[]

package/templates/default-workspace/books/03-technical-book-workflow/chapters/{01-build-flow.adoc → 010-build-flow.adoc}

@@ -1,4 +1,3 @@
-[#technical-build-flow]
 == 构建流程
 
 技术书仍然是一本文档边界独立的 book。它可以使用共享属性和共享图片，但自己的示例代码保留在书内。

package/templates/default-workspace/books/04-reference-manual/backmatter/glossary.adoc

@@ -4,5 +4,5 @@ book:: 具有独立 `book.adoc` 和构建产物的书籍单位。
 part:: 同一本 book 内部的 level 0 大分部。
 catalog:: 多书工作区的读者导航入口。
 shared resource:: 被 catalog 或多本书共同引用的资源。
-explicit anchor:: 使用 `[#id]` 写出的稳定引用目标。
+custom ID:: 用 `[#id]` 给标题加的另一个地址。标题就是地址；同名的标题写上级标题、以 `::` 隔开来引用，同一个上级下也同名或标题里有 `#`、`::` 时，才给它再加一个。
 contract check:: 对工作区源文件约定进行静态检查的脚本行为。

package/templates/default-workspace/books/04-reference-manual/book.adoc

@@ -15,13 +15,13 @@ include::../../shared/attributes.adoc[]
 [preface]
 include::frontmatter/preface.adoc[]
 
-include::chapters/01-decision-table.adoc[]
+include::chapters/010-decision-table.adoc[]
 
-include::chapters/02-path-rules.adoc[]
+include::chapters/020-path-rules.adoc[]
 
-include::chapters/03-xref-patterns.adoc[]
+include::chapters/030-xref-patterns.adoc[]
 
-include::chapters/04-growth-paths.adoc[]
+include::chapters/040-growth-paths.adoc[]
 
 [glossary]
 include::backmatter/glossary.adoc[]

package/templates/default-workspace/books/04-reference-manual/chapters/{01-decision-table.adoc → 010-decision-table.adoc}

@@ -1,4 +1,3 @@
-[#decision-table]
 == 结构选择表
 
 [cols="1,2,2", options="header"]

package/templates/default-workspace/books/04-reference-manual/chapters/{02-path-rules.adoc → 020-path-rules.adoc}

@@ -1,4 +1,3 @@
-[#path-rules]
 == 路径规则
 
 Book directory:: `books/<book-id>/`，一本独立 book 的边界。

package/templates/default-workspace/books/04-reference-manual/chapters/030-xref-patterns.adoc

@@ -0,0 +1,19 @@
+== 引用模式
+
+书内引用写目标那一节的标题：
+
+[source,asciidoc]
+----
+xref:结构选择表[]
+----
+
+跨书引用写向 AsciiDoc 源文件，`#` 后面写目标书里那一节的标题：
+
+[source,asciidoc]
+----
+xref + : + ../other-book/book.adoc#目标章节[]
+----
+
+上面的写法用分段文本展示，避免默认样本之间形成真实链接依赖。实际写作时去掉空格和加号，写成一个完整的 cross reference 宏。
+
+被跨书引用的标题不需要另写 anchor：标题就是地址，跨书与书内一样。目标标题改了名，`pnpm run check` 会指出每一处没有跟上的引用。

package/templates/default-workspace/books/04-reference-manual/chapters/{04-growth-paths.adoc → 040-growth-paths.adoc}

@@ -1,4 +1,3 @@
-[#growth-paths]
 == 工作区增长路径
 
 当前模板只把已经服务样本书、公共文档或脚本的目录放入源目录树。

package/templates/default-workspace/books/05-upper-volume/book.adoc

@@ -15,9 +15,9 @@ include::../../shared/attributes.adoc[]
 [preface]
 include::frontmatter/preface.adoc[]
 
-include::chapters/01-upper-opening.adoc[]
+include::chapters/010-upper-opening.adoc[]
 
-include::chapters/02-upper-core-model.adoc[]
+include::chapters/020-upper-core-model.adoc[]
 
 [bibliography]
 include::backmatter/bibliography.adoc[]