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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.0 - 2026-10-21
+
+### Added
+
+- `adoc-books.config.mjs` accepts `documentRoot`: how far books may include files, relative to the workspace root (default `.`). A workspace that lives inside a project repository declares the project root (`".."`) so books can include the project's own code. Reader source paths and the `// file:` markers of copied source are relative to it. It must be a path string that contains the workspace root.
+- `adoc-books.config.mjs` accepts `includeResolvers`: `{ prefix, resolve }` objects in the shape `asciidoc-abundant-tree` 0.2.1 accepts. One resolver serves both the HTML build and the reader data, so `include::<prefix>…[]` shows the same lines in both. The runtime checks that a resolver returns real lines of a file inside `documentRoot`; the Configure section of the default workspace README lists the rules a resolver follows.
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.2.1` (Asciidoctor.js 4 inside, asynchronous parsing). HTML is still rendered by `@asciidoctor/core` 3.
+- A book whose include graph `asciidoc-abundant-tree` cannot parse now fails `build` and `check`, and the error starts with the book id. Previously the runtime printed one warning and fell back to a cover-only reader page while the build succeeded. If a book includes files outside the workspace, declare `documentRoot`.
+- Xref targets and anchors are checked only on the generated HTML. The source-level codes `XREF_TARGET_MISSING` and `MISSING_ANCHOR` are gone; a missing target or anchor is reported as `HTML_RESOURCE_MISSING` or `HTML_ANCHOR_MISSING`. An xref to a non-entry `.adoc` file of another book (for example `parts/…/x.adoc`) now fails, because no HTML page is generated for it; link `book.adoc#<id>` instead.
+
+### Fixed
+
+- Cross-book xrefs to IDs declared as `[.role#id]`, `[[id]]`, `[id=id]`, or generated from a title no longer fail `check` with `MISSING_ANCHOR`.
+
+### Upgrading an existing workspace
+
+A generated workspace owns its `tools/adoc-books.mjs`. To adopt this release, create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.5.0 tmp-books`, copy its `tools/adoc-books.mjs` over yours, set `"asciidoc-abundant-tree": "^0.2.1"` in your `package.json`, and run `pnpm install`.
+
 ## 0.4.0 - 2026-10-21
 
 ### Added

package/dist/runtime/adoc-books.mjs

@@ -1,4 +1,5 @@
 #!/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";
@@ -8,8 +9,6 @@ import { parseAbundantTree } 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 XREF_PATTERN = /xref:([^\[#]+)(?:#([A-Za-z0-9_-]+))?\[/g;
-const ANCHOR_PATTERN = /^\[#([A-Za-z0-9_-]+)(?:[.,][^\]]*)?\]$/gm;
 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+.-]*:/;
@@ -35,15 +34,12 @@ function stringValue(value, fallback) {
 }
 async function loadRuntimeConfig(rootDir) {
     const configPath = path.join(rootDir, CONFIG_FILE);
-    if (!await existsFile(configPath))
-        return DEFAULT_CONFIG;
-    const configUrl = pathToFileURL(configPath);
-    configUrl.search = `mtime=${(await stat(configPath)).mtimeMs}`;
-    const module = await import(configUrl.href);
-    const rawConfig = objectValue(module.default ?? module);
+    const rawConfig = await existsFile(configPath) ? await importConfig(configPath) : {};
     const rawRootIndex = objectValue(rawConfig.rootIndex);
     const rawHomeLink = objectValue(rawConfig.homeLink);
     return {
+        documentRoot: documentRootValue(rootDir, rawConfig.documentRoot),
+        includeResolvers: includeResolversValue(rawConfig.includeResolvers),
         rootIndex: {
             redirectTo: stringValue(rawRootIndex.redirectTo, DEFAULT_CONFIG.rootIndex.redirectTo),
             title: stringValue(rawRootIndex.title, DEFAULT_CONFIG.rootIndex.title)
@@ -54,6 +50,41 @@ async function loadRuntimeConfig(rootDir) {
         }
     };
 }
+async function importConfig(configPath) {
+    const configUrl = pathToFileURL(configPath);
+    configUrl.search = `mtime=${(await stat(configPath)).mtimeMs}`;
+    const module = await import(configUrl.href);
+    return objectValue(module.default ?? module);
+}
+// 相对工作区根解析：配置文件就在工作区根，".." 即项目根。书要 include ../../shared/attributes.adoc，所以根必须
+// 包含工作区；不合规的值直接报错，悄悄退回默认值时，使用者只会看到 include 越界，想不到是配置没生效。
+function documentRootValue(rootDir, value) {
+    if (value === undefined)
+        return rootDir;
+    if (typeof value !== "string" || value === "") {
+        throw new Error(`${CONFIG_FILE}: documentRoot must be a path string relative to the workspace root`);
+    }
+    const documentRoot = path.resolve(rootDir, value);
+    if (!isWithin(documentRoot, rootDir)) {
+        throw new Error(`${CONFIG_FILE}: documentRoot must contain the workspace root ${rootDir}, got ${documentRoot}`);
+    }
+    return documentRoot;
+}
+function isWithin(root, filePath) {
+    const relative = path.relative(root, filePath);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function includeResolversValue(value) {
+    if (value === undefined)
+        return [];
+    const valid = Array.isArray(value) && value.every((resolver) => {
+        const entry = objectValue(resolver);
+        return typeof entry.prefix === "string" && entry.prefix !== "" && typeof entry.resolve === "function";
+    });
+    if (!valid)
+        throw new Error(`${CONFIG_FILE}: includeResolvers must be an array of { prefix, resolve } objects`);
+    return value;
+}
 async function existsFile(filePath) {
     try {
         const stats = await stat(filePath);
@@ -138,6 +169,112 @@ function createAsciidoctor(loadKroki) {
     }
     return asciidoctor;
 }
+// 书架登记的 include 解析器，在 HTML 这一侧由 Asciidoctor 的 include 处理器调用；阅读数据一侧由 aat 调用同一份，
+// 两侧读同一份行（DESIGN.adoc 的 Workspace Configuration）。每次构建单独一个 registry：Asciidoctor 3 的全局扩展
+// 在进程里一直留着，登记在全局会把上一个工作区的解析器带进下一个。
+function includeResolverRegistry(asciidoctor, config) {
+    if (config.includeResolvers.length === 0)
+        return asciidoctor.Extensions.create();
+    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),
+                        // aat 一侧对留空的位置属性同样交 null，它的类型声明没有写出来。
+                        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);
+            });
+        });
+    });
+}
+// 解析器交回的是来源文件里从 startLine 起连续的整行。这里逐行核对：两侧读同一份行的前提是 origin 就是 text 的
+// 出处——aat 把 origin 指向的文件全文收进复制纯文本，HTML 只用 text，两者对不上时构建也会成功，读者却看到两份
+// 不同的东西（aat 对此只报 warning）。
+function checkedResolution(resolution, documentRoot, who, location) {
+    const shaped = objectValue(resolution);
+    const origin = objectValue(shaped.origin);
+    const startLine = origin.startLine;
+    if (typeof shaped.text !== "string" || typeof origin.path !== "string" || !Number.isInteger(startLine) || startLine < 1) {
+        throw new Error(`${who} returned an invalid result for ${location}; expected { text, origin: { path, startLine } }`);
+    }
+    const absolutePath = path.resolve(documentRoot, origin.path);
+    // 来源是根之内的一个文件，不能是根本身；aat 同样拒绝。
+    if (absolutePath === documentRoot || !isWithin(documentRoot, absolutePath)) {
+        throw new Error(`${who} returned a source outside documentRoot ${documentRoot} for ${location}: ${absolutePath}`);
+    }
+    const text = withoutFinalNewline(shaped.text);
+    if (text !== "") {
+        const lines = text.split(/\r?\n/u);
+        let source;
+        try {
+            source = readFileSync(absolutePath, "utf8");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${who} returned a source that cannot be read for ${location}: ${message}`, { cause: error });
+        }
+        const sourceLines = withoutFinalNewline(source).split(/\r?\n/u);
+        const first = startLine - 1;
+        const mismatch = lines.findIndex((line, index) => sourceLines[first + index] !== line);
+        if (mismatch !== -1) {
+            const lineNumber = first + mismatch + 1;
+            const detail = lineNumber > sourceLines.length
+                ? `the file has only ${sourceLines.length} lines`
+                : `line ${lineNumber} is ${shown(sourceLines[lineNumber - 1])}, the resolver returned ${shown(lines[mismatch])}`;
+            throw new Error(`${who} returned text that is not lines ${first + 1}-${first + lines.length} of ${absolutePath} for ${location}: ${detail}`);
+        }
+    }
+    return { text, absolutePath, startLine: startLine };
+}
+// 末尾的换行是最后一行的结束，不是多出来的一行：留着会让 Reader 多切出一个空行（aat 同样去掉一个）。来源文件按同一
+// 规则切行，文件最后一行之后才不会多出一个并不存在的空行。
+function withoutFinalNewline(text) {
+    return text.replace(/\r?\n$/u, "");
+}
+// 消息里的一行：截短，BOM 与控制字符写成可见的转义，行尾空白看得出来。
+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";
@@ -181,7 +318,7 @@ function formatAsciidoctorMessage(message) {
     const text = messageText(message);
     return location ? `${severity}: ${location}: ${text}` : `${severity}: ${text}`;
 }
-function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
+function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir, attributes = {}) {
     const loggerManager = asciidoctor.LoggerManager;
     const defaultLogger = loggerManager.getLogger();
     const memoryLogger = asciidoctor.MemoryLogger.create();
@@ -192,6 +329,7 @@ function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
             base_dir: baseDir,
             to_file: outputFile,
             mkdirs: true,
+            extension_registry: extensionRegistry,
             attributes
         });
     }
@@ -203,13 +341,13 @@ function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
         throw new Error(`AsciiDoc strict check failed for ${input}\n${messages.map(formatAsciidoctorMessage).join("\n")}`);
     }
 }
-async function buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams) {
+async function buildHtml(rootDir, books, asciidoctor, extensionRegistry, useKroki, fetchDiagrams) {
     await mkdir(path.join(rootDir, "build", "html"), { recursive: true });
-    convertFile(asciidoctor, path.join(rootDir, "catalog.adoc"), path.join(rootDir, "build", "html", "catalog.html"), rootDir);
+    convertFile(asciidoctor, 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, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
+        convertFile(asciidoctor, extensionRegistry, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
             ...(useKroki && fetchDiagrams ? { "kroki-fetch-diagram": "", "kroki-http-method": "post" } : {})
         });
     }
@@ -316,50 +454,29 @@ function assertNoToolErrors(bookId, diagnostics) {
         }
     }
 }
-function sourceBundleFromDocument(document, fallbackPath, fallbackSource) {
+function sourceBundleFromDocument(document) {
     const sourceFiles = Array.isArray(document.sourceFiles) ? document.sourceFiles : [];
     const files = sourceFiles.filter((file) => typeof file.relativePath === "string" && typeof file.raw === "string");
-    if (files.length === 0)
-        return fallbackSource;
     return files.map((file) => {
         const body = file.raw?.endsWith("\n") ? file.raw : `${file.raw ?? ""}\n`;
-        return `// file: ${file.relativePath ?? fallbackPath}\n${body}`;
+        return `// file: ${file.relativePath}\n${body}`;
     }).join("\n");
 }
-function fallbackReaderBookData(rootDir, book, fallbackSource, reason) {
-    console.warn(`${book.bookId}: reader page map fell back to cover-only mode: ${reason}`);
-    const entry = path.relative(rootDir, book.input).split(path.sep).join("/");
-    return {
-        pageMap: {
-            version: 1,
-            book: {
-                id: book.bookId,
-                title: book.bookId,
-                entry
-            },
-            pages: [{
-                    id: "cover",
-                    kind: "cover",
-                    title: book.bookId,
-                    anchors: [],
-                    toc: []
-                }]
-        },
-        sourceBundle: fallbackSource
-    };
-}
-function buildReaderBookData(rootDir, book, fallbackSource) {
+// 解析失败就让构建失败，不退回只有封面的阅读页：退回时 include 越过 documentRoot 只剩一条 warning，
+// 构建照常成功，没有人发现阅读页坏了（DESIGN.adoc 的 Workspace Contract Checks）。
+async function buildReaderBookData(config, book) {
     let document;
     try {
-        document = parseAbundantTree({
+        document = await parseAbundantTree({
             sourcePath: book.input,
             mode: "book-entry",
-            documentRoot: rootDir
+            documentRoot: config.documentRoot,
+            includeResolvers: config.includeResolvers
         });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return fallbackReaderBookData(rootDir, book, fallbackSource, message);
+        throw new Error(`${book.bookId}: ${message}`, { cause: error });
     }
     const diagnostics = Array.isArray(document.toolDiagnostics) ? document.toolDiagnostics : [];
     assertNoToolErrors(book.bookId, diagnostics);
@@ -421,13 +538,13 @@ function buildReaderBookData(rootDir, book, fallbackSource) {
         book: {
             id: book.bookId,
             title: pages[0].title,
-            entry: path.relative(rootDir, book.input).split(path.sep).join("/")
+            entry: path.relative(config.documentRoot, book.input).split(path.sep).join("/")
         },
         pages
     };
     return {
         pageMap,
-        sourceBundle: sourceBundleFromDocument(document, pageMap.book.entry, fallbackSource)
+        sourceBundle: sourceBundleFromDocument(document)
     };
 }
 function readerStyles() {
@@ -943,15 +1060,14 @@ ${readerStyles()}
 <script>${readerScript()}</script>`;
     return `${html.slice(0, insertAt)}${withReaderScript}${html.slice(insertAt)}`;
 }
-async function addHomeLinks(rootDir, books, homeLink) {
+async function addHomeLinks(rootDir, books, config) {
     const catalog = path.join(rootDir, "build", "html", "catalog.html");
     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 fallbackSource = await combinedBookSource(book.bookDir);
-        const readerData = buildReaderBookData(rootDir, book, fallbackSource);
-        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
+        const readerData = await buildReaderBookData(config, book);
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
     }
 }
 async function writeRootIndex(rootDir, rootIndex) {
@@ -977,27 +1093,12 @@ function extractCatalogBookIds(catalogSource) {
         ids.add(match[1]);
     return [...ids].sort((a, b) => a.localeCompare(b));
 }
-function explicitAnchors(source) {
-    const anchors = new Set();
-    for (const match of source.matchAll(ANCHOR_PATTERN))
-        anchors.add(match[1]);
-    return anchors;
-}
-function attributesFromBookSource(bookSource) {
-    const attributes = new Map();
-    for (const line of bookSource.split(/\r?\n/)) {
-        const match = line.match(/^:([A-Za-z0-9_-]+):\s+(.+)$/);
-        if (match)
-            attributes.set(match[1], match[2]);
-    }
-    return attributes;
-}
-function expandXrefTarget(target, attributes) {
-    return target.replaceAll(/\{([A-Za-z0-9_-]+)\}/g, (_, name) => attributes.get(name) ?? `{${name}}`);
-}
 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 认得全。
 async function workspaceContractIssues(rootDir, books) {
     const issues = [];
     const catalogSource = await readIfExists(path.join(rootDir, "catalog.adoc"));
@@ -1014,31 +1115,8 @@ async function workspaceContractIssues(rootDir, books) {
     }
     for (const book of books) {
         const bookSource = await readFile(book.input, "utf8");
-        const allSource = await combinedBookSource(book.bookDir);
-        const attributes = attributesFromBookSource(bookSource);
         if (!/^:doctype:\s+book$/m.test(bookSource))
             issues.push(issue("MISSING_DOCTYPE", book.bookId));
-        for (const match of allSource.matchAll(XREF_PATTERN)) {
-            const [, target, anchor] = match;
-            if (/^https?:/.test(target))
-                continue;
-            const expandedTarget = expandXrefTarget(target, attributes);
-            if (!expandedTarget.endsWith(".adoc"))
-                continue;
-            const resolved = path.resolve(book.bookDir, expandedTarget);
-            if (!await existsFile(resolved)) {
-                issues.push(issue("XREF_TARGET_MISSING", `${book.bookId} -> ${expandedTarget}`));
-                if (anchor)
-                    issues.push(issue("MISSING_ANCHOR", `${book.bookId} -> ${expandedTarget}#${anchor}`));
-                continue;
-            }
-            if (anchor) {
-                const targetSource = await combinedBookSource(path.dirname(resolved));
-                if (!explicitAnchors(targetSource).has(anchor)) {
-                    issues.push(issue("MISSING_ANCHOR", `${book.bookId} -> ${expandedTarget}#${anchor}`));
-                }
-            }
-        }
     }
     return issues;
 }
@@ -1125,9 +1203,9 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const useKroki = await workspaceUsesDiagrams(rootDir, books);
     const fetchDiagrams = shouldFetchDiagrams();
     const asciidoctor = createAsciidoctor(useKroki);
-    await buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams);
+    await buildHtml(rootDir, books, asciidoctor, includeResolverRegistry(asciidoctor, config), useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
-    await addHomeLinks(rootDir, books, config.homeLink);
+    await addHomeLinks(rootDir, books, config);
     await writeRootIndex(rootDir, config.rootIndex);
     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.4.0",
+  "version": "0.5.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.1.18",
+    "asciidoc-abundant-tree": "^0.2.1",
     "asciidoctor-kroki": "^0.18.1",
     "playwright": "^1.59.1",
     "typescript": "^5.9.3"

package/templates/default-workspace/README.md

@@ -35,7 +35,50 @@ ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
 pnpm run check
 ```
 
-This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources.
+This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources, and that every book's includes stay within `documentRoot` (see Configure).
+
+## Configure
+
+An optional `adoc-books.config.mjs` at the workspace root adjusts the build. Every key is optional:
+
+```js
+export default {
+  // Where build/html/index.html redirects, and its page title.
+  rootIndex: { redirectTo: "catalog.html", title: "My Books" },
+  // The catalog link at the top of every book.
+  homeLink: { label: "Back to catalog", subtitle: "My Books" },
+  // How far books may include files, relative to this directory. Default: "." (this workspace).
+  // documentRoot: "..",
+};
+```
+
+`documentRoot` matters when this workspace lives inside a project repository. Set it to the project root (`".."` when the workspace is a direct subdirectory) and books can include the project's own code instead of a copy of it. Source paths in the reader and the `// file:` markers of copied source then start at that root. It must contain this workspace. An include that leaves `documentRoot` fails `pnpm run check` and names the book.
+
+`includeResolvers` lets books include lines chosen by your own code, for example one function out of a source file:
+
+```js
+import path from "node:path";
+
+export default {
+  includeResolvers: [{
+    prefix: "symbol:",
+    // include::symbol:src/math.ts[add] arrives as { target: "src/math.ts", attributes: { 1: "add" }, sourcePath }.
+    resolve({ target, attributes, sourcePath }) {
+      const file = path.resolve(import.meta.dirname, target); // this resolver reads targets from the workspace root
+      // ...read file and find the lines of the function named attributes[1]...
+      return { text, origin: { path: file, startLine } };
+    },
+  }],
+};
+```
+
+The same resolver serves the HTML build and the reader, so both show the same lines. When you write one:
+
+- End `prefix` with a separator such as `:`. Prefixes match the start of the include target, so `snip` would also take `include::snippets/x.adoc[]`.
+- Decide what `target` is relative to. The example uses the workspace root; for Asciidoctor's own rule use `path.dirname(sourcePath)`.
+- Return whole consecutive lines of one file inside `documentRoot`, that file's path (absolute, or relative to `documentRoot`), and the line number (from 1) where the text starts. The build checks that the text is exactly those lines of that file, trailing spaces and a leading byte order mark included, and names the first line that differs. Build messages about those lines point into the file. Copied source includes that whole file.
+- Return the result directly, not a Promise, and return the same result every time: `resolve` runs twice per directive, once for the HTML and once for the reader.
+- Attribute values are strings, except that an empty leading positional attribute (`[,x]`) is `null`. Do not leave a positional attribute empty between others (`[a,,b]`); the two sides would number them differently.
 
 ## Clean
 

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

@@ -13,7 +13,7 @@
   },
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
-    "asciidoc-abundant-tree": "^0.1.18",
+    "asciidoc-abundant-tree": "^0.2.1",
     "asciidoctor-kroki": "^0.18.1"
   }
 }

package/templates/solo-workspace/README.md

@@ -17,6 +17,22 @@ To fetch diagram images into the local HTML output instead of linking Kroki URLs
 ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
 ```
 
+## Configure
+
+An optional `adoc-books.config.mjs` at the workspace root adjusts the build. When this workspace lives inside a
+project repository, declare the project root so books can include the project's own code:
+
+```js
+export default {
+  documentRoot: "..", // relative to this directory; default "."
+};
+```
+
+The file also accepts `rootIndex: { redirectTo, title }`, `homeLink: { label, subtitle }`, and
+`includeResolvers: [{ prefix, resolve }]` for include directives whose lines your own code selects.
+The rules a resolver follows are in the
+[Configure section of the default workspace README](https://github.com/MichengLiang/asciidoc-multi-book-workspace/blob/main/templates/default-workspace/README.md#configure).
+
 ## Add A Book
 
 Copy `books/01-structured-writing-conventions` to `books/<NN-book-id>`, edit its `book.adoc`, then add an