create-asciidoc-multi-book-workspace 0.1.1 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.1.7 - 2026-06-13
+
+### Added
+
+- Add a `复制本书为纯文本` control to each generated book page so readers can copy the expanded single-file book text for saving, note-taking, or model analysis.
+- Add a browser fallback that opens the expanded book text as a UTF-8 plain-text page when clipboard access is unavailable.
+
+### Changed
+
+- Keep the generated book page controls self-contained by embedding the already-reduced book text in the HTML instead of adding another published source file.
+
+## 0.1.6 - 2026-06-09
+
+### Added
+
+- Accept typed explicit anchors such as `[#id.role, key=value]` when validating user-authored xrefs.
+- Add optional `adoc-books.config.mjs` support so generated workspaces can customize the root redirect and book home-link copy.
+- Add a structured writing conventions reference document and expand the generated sample's appendix with cross-file xref path guidance.
+
+### Changed
+
+- Keep generated workspaces catalog-oriented by default while allowing user-owned navigation semantics through configuration.
+
+## 0.1.5 - 2026-06-07
+
+### Added
+
+- Add a maintainer guide for Asciidoctor book part numbering, including the boundary between `sectnums`, `partnums`, and `part-signifier`.
+- Add runtime and sample contract coverage for the structured writing conventions book's generated part labels.
+
+### Changed
+
+- Enable native `Part I` style part numbering in `07-structured-writing-conventions`.
+- Expand the structured writing conventions sample text with additional reader-facing context.
+
+## 0.1.4 - 2026-06-06
+
+### Added
+
+- Add `07-structured-writing-conventions`, a default workspace sample book for structured writing conventions.
+- Document how headings, stable IDs, role tokens, xrefs, rel predicates, and named attributes form a readable and projection-friendly source surface.
+- Add sample contract coverage for the structured writing conventions book.
+
+### Changed
+
+- Update the default workspace catalog and README to include structured writing conventions without tying README wording to a fixed sample count.
+
+## 0.1.3 - 2026-06-06
+
+### Added
+
+- Expand the book anatomy sample with part directory guidance, chapter numbering notes, and inline structure markers.
+- Add sample contract checks for semantic inline roles, path roles, explicit anchors, xrefs, and index term macro usage.
+- Guard the npm package boundary against generated HTML output entering the published template.
+
+### Changed
+
+- Clarify that the anatomy sample shows structure positions and combinations, not a required checklist for every book.
+- Use explicit `indexterm2` and `indexterm` macro syntax in the anatomy sample.
+
+## 0.1.2 - 2026-06-06
+
+### Added
+
+- Export the workspace initializer from the package root for host CLI integration.
+- Publish TypeScript declaration files for the public initializer API.
+
+### Changed
+
+- Return the resolved target directory and generated package name from `initWorkspace`.
+- Document the library entrypoint while keeping command parsing and user-facing output owned by host CLIs.
+
 ## 0.1.1 - 2026-06-06
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 `create-asciidoc-multi-book-workspace` is an npm initializer for a complete AsciiDoc multi-book workspace.
 
-It creates a user-owned workspace with seven sample books, a catalog, shared assets, explicit AsciiDoc dependencies, and one local build script at `tools/adoc-books.mjs`.
+It creates a user-owned workspace with sample books, a catalog, shared assets, explicit AsciiDoc dependencies, and one local build script at `tools/adoc-books.mjs`.
 
 ## Usage
 
@@ -23,6 +23,19 @@ npm create asciidoc-multi-book-workspace@latest my-books
 npx create-asciidoc-multi-book-workspace@latest my-books
 ```
 
+## Library API
+
+Host CLIs can create the same workspace through the package entrypoint:
+
+```ts
+import { initWorkspace } from "create-asciidoc-multi-book-workspace";
+
+const result = await initWorkspace({ targetDir: "my-books", force: false });
+console.log(result.targetDir);
+```
+
+The host CLI owns command parsing and user-facing output. This package owns the workspace files it creates.
+
 The generated workspace contains:
 
 ```text
@@ -38,6 +51,7 @@ books/03-technical-book-workflow
 books/04-reference-manual
 books/05-upper-volume
 books/06-lower-volume
+books/07-structured-writing-conventions
 shared/attributes.adoc
 shared/images/workspace-map.svg
 ```
@@ -72,7 +86,7 @@ DESIGN.adoc                  # maintainer design specification
 .github/                     # maintainer CI
 ```
 
-The seven sample books live only under `templates/default-workspace/books/`.
+The sample books live only under `templates/default-workspace/books/`.
 
 ## Maintainer Commands
 

package/dist/build-template-preview.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+export interface RunCommandOptions {
+    cwd: string;
+}
+export type RunCommand = (command: string, args: string[], options: RunCommandOptions) => Promise<void>;
+export interface BuildTemplatePreviewOptions {
+    previewRoot?: string;
+    runCommand?: RunCommand;
+    fresh?: boolean;
+    install?: boolean;
+}
+export interface BuildTemplatePreviewResult {
+    previewRoot: string;
+    workspaceDir: string;
+    htmlDir: string;
+}
+export declare function buildTemplatePreview(options?: BuildTemplatePreviewOptions): Promise<BuildTemplatePreviewResult>;

package/dist/create.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/create.js

@@ -23,8 +23,8 @@ async function main() {
         process.exitCode = 1;
         return;
     }
-    const created = await initWorkspace({ targetDir: target, force: args.includes("--force") });
-    const displayTarget = path.relative(process.cwd(), created) || ".";
+    const result = await initWorkspace({ targetDir: target, force: args.includes("--force") });
+    const displayTarget = path.relative(process.cwd(), result.targetDir) || ".";
     console.log(`Created AsciiDoc multi-book workspace in ${displayTarget}`);
     console.log("");
     console.log("Next:");

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { initWorkspace } from "./init-workspace.js";
+export type { InitWorkspaceOptions, InitWorkspaceResult } from "./init-workspace.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { initWorkspace } from "./init-workspace.js";

package/dist/init-workspace.d.ts

@@ -0,0 +1,9 @@
+export interface InitWorkspaceOptions {
+    targetDir: string;
+    force?: boolean;
+}
+export interface InitWorkspaceResult {
+    targetDir: string;
+    packageName: string;
+}
+export declare function initWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;

package/dist/init-workspace.js

@@ -54,5 +54,5 @@ export async function initWorkspace(options) {
     await writeFile(path.join(targetDir, ".gitignore"), await readFile(path.join(templateRoot, "gitignore.template"), "utf8"), "utf8");
     await mkdir(path.join(targetDir, "tools"), { recursive: true });
     await cp(runtimeScript, path.join(targetDir, "tools", "adoc-books.mjs"), { force: true });
-    return targetDir;
+    return { targetDir, packageName };
 }

package/dist/runtime/adoc-books.mjs

@@ -2,16 +2,55 @@
 import { createRequire } from "node:module";
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 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 ANCHOR_PATTERN = /^\[#([A-Za-z0-9_-]+)(?:[.,][^\]]*)?\]$/gm;
 const LOCAL_TARGET_PATTERN = /\b(?:href|src)="([^"]+)"/g;
 const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
 const HOME_MARKER = "data-multi-book-home";
+const CONTROLS_MARKER = "data-multi-book-controls";
 const FETCH_DIAGRAMS_ENV = "ADOC_BOOKS_FETCH_DIAGRAMS";
+const CONFIG_FILE = "adoc-books.config.mjs";
+const DEFAULT_CONFIG = {
+    rootIndex: {
+        redirectTo: "catalog.html",
+        title: "AsciiDoc Multi-Book Workspace"
+    },
+    homeLink: {
+        label: "Back to catalog",
+        subtitle: "AsciiDoc multi-book workspace"
+    }
+};
+function objectValue(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function stringValue(value, fallback) {
+    return typeof value === "string" && value.trim() !== "" ? 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 rawRootIndex = objectValue(rawConfig.rootIndex);
+    const rawHomeLink = objectValue(rawConfig.homeLink);
+    return {
+        rootIndex: {
+            redirectTo: stringValue(rawRootIndex.redirectTo, DEFAULT_CONFIG.rootIndex.redirectTo),
+            title: stringValue(rawRootIndex.title, DEFAULT_CONFIG.rootIndex.title)
+        },
+        homeLink: {
+            label: stringValue(rawHomeLink.label, DEFAULT_CONFIG.homeLink.label),
+            subtitle: stringValue(rawHomeLink.subtitle, DEFAULT_CONFIG.homeLink.subtitle)
+        }
+    };
+}
 async function existsFile(filePath) {
     try {
         const stats = await stat(filePath);
@@ -170,29 +209,35 @@ function escapeHtmlAttribute(value) {
         .replaceAll("<", "&lt;")
         .replaceAll(">", "&gt;");
 }
-function addHomeLinkToBookHtml(html, href) {
-    if (html.includes(HOME_MARKER))
+function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replaceAll("<", "\\u003c")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+}
+function addBookControlsToBookHtml(html, href, homeLink, bookSource) {
+    if (html.includes(CONTROLS_MARKER))
         return html;
     const marker = '<div id="toc" class="toc2">';
     const index = html.indexOf(marker);
     if (index === -1)
         throw new Error("book HTML is missing the left TOC container");
     const insertAt = index + marker.length;
-    const homeBlock = `
+    const controlsBlock = `
 <style>
-.multi-book-home {
+.multi-book-controls {
   margin: 0 0 1rem;
   padding-bottom: .75rem;
   border-bottom: 1px solid #e5e7eb;
 }
-.multi-book-home a {
+.multi-book-home {
   color: #1f2937;
   display: block;
   font-weight: 600;
   line-height: 1.35;
   text-decoration: none;
 }
-.multi-book-home a:hover {
+.multi-book-home:hover {
   color: #0f766e;
   text-decoration: underline;
 }
@@ -203,33 +248,116 @@ function addHomeLinkToBookHtml(html, href) {
   font-weight: 400;
   margin-top: .15rem;
 }
+.multi-book-copy-source {
+  appearance: none;
+  background: #ffffff;
+  border: 1px solid #cbd5e1;
+  border-radius: 4px;
+  color: #1f2937;
+  cursor: pointer;
+  display: block;
+  font-size: .82rem;
+  font-weight: 600;
+  line-height: 1.2;
+  margin-top: .75rem;
+  padding: .42rem .5rem;
+  text-align: center;
+  width: 100%;
+}
+.multi-book-copy-source:hover,
+.multi-book-copy-source:focus {
+  border-color: #0f766e;
+  color: #0f766e;
+}
+.multi-book-copy-status {
+  color: #64748b;
+  display: block;
+  font-size: .75rem;
+  line-height: 1.35;
+  margin-top: .4rem;
+  min-height: 1em;
+}
 </style>
-<div class="multi-book-home" ${HOME_MARKER}>
-  <a href="${escapeHtmlAttribute(href)}">Back to catalog<span>AsciiDoc multi-book workspace</span></a>
-</div>`;
-    return `${html.slice(0, insertAt)}${homeBlock}${html.slice(insertAt)}`;
+<div class="multi-book-controls" ${CONTROLS_MARKER}>
+  <a class="multi-book-home" ${HOME_MARKER} href="${escapeHtmlAttribute(href)}">${escapeHtmlAttribute(homeLink.label)}<span>${escapeHtmlAttribute(homeLink.subtitle)}</span></a>
+  <button type="button" class="multi-book-copy-source" data-multi-book-source-copy>复制本书为纯文本</button>
+  <span class="multi-book-copy-status" data-multi-book-source-status aria-live="polite"></span>
+</div>
+<script type="application/json" id="multi-book-source-data">${escapeJsonScript(bookSource)}</script>
+<script>
+(function () {
+  var sourceElement = document.getElementById("multi-book-source-data");
+  var button = document.querySelector("[data-multi-book-source-copy]");
+  var status = document.querySelector("[data-multi-book-source-status]");
+  if (!sourceElement || !button) return;
+
+  var source = "";
+  var fallbackMode = false;
+  try {
+    source = JSON.parse(sourceElement.textContent || '""');
+  } catch (error) {
+    if (status) status.textContent = "纯文本数据读取失败";
+    button.disabled = true;
+    return;
+  }
+
+  function setStatus(message) {
+    if (status) status.textContent = message;
+  }
+
+  function openSourcePage() {
+    var blob = new Blob([source], { type: "text/plain;charset=utf-8" });
+    var url = URL.createObjectURL(blob);
+    window.open(url, "_blank", "noopener");
+    setTimeout(function () { URL.revokeObjectURL(url); }, 60000);
+    setStatus("已尝试打开纯文本页；如果没有出现，请允许弹出窗口后再试");
+  }
+
+  button.addEventListener("click", async function () {
+    if (fallbackMode) {
+      openSourcePage();
+      return;
+    }
+
+    try {
+      if (!navigator.clipboard || !navigator.clipboard.writeText) throw new Error("clipboard unavailable");
+      await navigator.clipboard.writeText(source);
+      button.textContent = "已复制";
+      setStatus("");
+      setTimeout(function () { button.textContent = "复制本书为纯文本"; }, 1800);
+    } catch (error) {
+      fallbackMode = true;
+      button.textContent = "打开纯文本页";
+      openSourcePage();
+    }
+  });
+}());
+</script>`;
+    return `${html.slice(0, insertAt)}${controlsBlock}${html.slice(insertAt)}`;
 }
-async function addHomeLinks(rootDir, books) {
+async function addHomeLinks(rootDir, books, homeLink) {
     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);
-        await writeFile(htmlFile, addHomeLinkToBookHtml(html, href), "utf8");
+        const source = await readFile(path.join(rootDir, "build", "adoc", "books", `${book.bookId}.adoc`), "utf8");
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, homeLink, source), "utf8");
     }
 }
-async function writeRootIndex(rootDir) {
+async function writeRootIndex(rootDir, rootIndex) {
     const outputDir = path.join(rootDir, "build", "html");
     await mkdir(outputDir, { recursive: true });
+    const redirectTo = rootIndex.redirectTo;
     await writeFile(path.join(outputDir, "index.html"), `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
-  <meta http-equiv="refresh" content="0; url=catalog.html">
-  <title>AsciiDoc Multi-Book Workspace</title>
+  <meta http-equiv="refresh" content="0; url=${escapeHtmlAttribute(redirectTo)}">
+  <title>${escapeHtmlAttribute(rootIndex.title)}</title>
 </head>
 <body>
-  <p><a href="catalog.html">catalog.html</a></p>
+  <p><a href="${escapeHtmlAttribute(redirectTo)}">${escapeHtmlAttribute(redirectTo)}</a></p>
 </body>
 </html>
 `, "utf8");
@@ -351,14 +479,15 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const books = await discoverBooks(rootDir);
     if (books.length === 0)
         throw new Error(`missing book.adoc entries in ${path.join(rootDir, "books")}`);
+    const config = await loadRuntimeConfig(rootDir);
     const useKroki = await workspaceUsesDiagrams(rootDir, books);
     const fetchDiagrams = shouldFetchDiagrams();
     const asciidoctor = createAsciidoctor(useKroki);
     await buildReducedAdoc(rootDir, books, asciidoctor);
     await buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
-    await addHomeLinks(rootDir, books);
-    await writeRootIndex(rootDir);
+    await addHomeLinks(rootDir, books, config.homeLink);
+    await writeRootIndex(rootDir, config.rootIndex);
     await assertNoIssues("HTML local resource check", await missingLocalResources(rootDir));
     await assertNoIssues("workspace contract check", await workspaceContractIssues(rootDir, books));
 }

package/dist/template-manifest.d.ts

@@ -0,0 +1,3 @@
+export declare const defaultWorkspaceTemplate = "default-workspace";
+export declare const templatePackageNamePlaceholder = "{{name}}";
+export declare const fixedTemplateOutputPaths: readonly ["README.md", "catalog.adoc", "package.json", ".gitignore", "tools/adoc-books.mjs", "books", "shared"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.1.1",
+  "version": "0.1.7",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -17,6 +17,13 @@
   },
   "homepage": "https://michengliang.github.io/asciidoc-multi-book-workspace/",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
   "keywords": [
     "asciidoc",
     "asciidoctor",
@@ -30,7 +37,9 @@
   },
   "files": [
     "dist/build-template-preview.js",
+    "dist/*.d.ts",
     "dist/create.js",
+    "dist/index.js",
     "dist/init-workspace.js",
     "dist/runtime/adoc-books.mjs",
     "dist/template-manifest.js",

package/templates/default-workspace/README.md

@@ -1,6 +1,6 @@
 # My Books
 
-This is an AsciiDoc multi-book workspace. It starts with seven sample books that show common ways to organize independent books, multipart books, technical books, reference material, and split volumes.
+This is an AsciiDoc multi-book workspace. It starts with sample books that show common ways to organize independent books, multipart books, technical books, reference material, split volumes, and structured writing conventions.
 
 ## Install
 

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

@@ -4,8 +4,11 @@
 |===
 |写法 |含义
 
-|`= 书名或文档名`
-|Document title（文档标题，Level 0）。在 book 文档类型中也可作为 Part（部）。
+|`= 书名`
+|Document title（文档标题）。在 book 文档类型中作为整本书标题。
+
+|`= 部标题`
+|Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。
 
 |`== 章`
 |Level 1 Section（一级章节）。在 book 文档类型中通常作为 Chapter（章）。
@@ -22,3 +25,5 @@
 |`====== 最底层级`
 |Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。
 |===
+
+`[appendix]`、`[glossary]`、`[bibliography]` 和 `[index]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。

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

@@ -1,4 +1,6 @@
 = 参考资料
 
+每条参考资料可使用 bibliography anchor 作为稳定引用目标。
+
 * [[[asciidoctor-section-styles]]] Asciidoctor Docs, Section Styles for Articles and Books, https://docs.asciidoctor.org/asciidoc/latest/sections/styles/
 * [[[asciidoctor-parts]]] Asciidoctor Docs, Book Parts, https://docs.asciidoctor.org/asciidoc/latest/sections/parts/

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

@@ -1,5 +1,7 @@
 = 术语表
 
+术语表通常使用定义列表记录术语和解释。
+
 book:: 具有独立 `book.adoc`、章节顺序和构建产物的书籍单位。
 part:: 同一本 book 内部的 level 0 大分部。
 chapter:: book 中的主要正文单位，通常使用 `==` 标题。
@@ -7,4 +9,4 @@ section:: chapter 内部的层级标题。
 appendix:: 放置补充材料的后置章节。
 glossary:: 使用定义列表解释术语的后置章节。
 bibliography:: 放置参考资料的后置章节。
-index:: 放置索引入口的后置章节。
+index:: 放置索引目录种子或索引说明的后置章节；自动索引目录依赖转换器支持。

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

@@ -1,9 +1,37 @@
 = 索引
 
-索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源：
+索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源。
+
+AsciiDoc 区分正文可见索引词和正文隐藏索引词：
+
+[cols="1,2", options="header"]
+|===
+|写法 |含义
+
+|`indexterm2:[<primary>]`
+|正文可见，同时作为一级索引项。
+
+|`indexterm:[<primary>]`
+|正文不可见，作为一级索引项。
+
+|`indexterm:[<primary>, <secondary>]`
+|正文不可见，作为二级索引项。
+
+|`indexterm:[<primary>, <secondary>, <tertiary>]`
+|正文不可见，作为三级索引项。
+|===
+
+正文中已经出现该词时，优先使用正文可见索引词。正文没有出现该词，但当前位置需要进入索引时，才使用正文隐藏索引词。
+
+隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾，避免形成独立空段落。
+
+Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。`[index]` section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。
+
+本书正文中的索引词示例：
 
 [source,asciidoc]
 ----
-(((section)))
-(((discrete heading)))
+indexterm2:[section]
+indexterm:[section, hierarchy]
+indexterm:[heading, discrete]
 ----

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

@@ -41,6 +41,8 @@ include::parts/02-body-structure/_partintro.adoc[]
 
 include::parts/02-body-structure/01-body-map.adoc[]
 
+include::parts/02-body-structure/02-inline-structure.adoc[]
+
 [appendix]
 include::backmatter/appendix-a.adoc[]
 

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

@@ -1,5 +1,5 @@
 == 摘要
 
-本书是 AsciiDoc book 的结构标本。它集中展示前置内容、正文分部、章节层级、附录、术语表、参考资料和索引在书稿中的位置。
+本书是 AsciiDoc book 的常见结构标本。它集中展示前置内容、正文分部、章节层级、附录、术语表、参考资料和索引在书稿中的位置及组合规则。
 
-本书用于学习完整结构，不作为日常新书的复制起点。
+本书用于学习常见结构组合，不作为日常新书的复制起点。

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

@@ -2,4 +2,6 @@
 
 这本标本书按结构位置组织，而不是按主题展开。阅读时先看 `book.adoc`，再对照各个被 include 的文件。
 
+读者可以观察结构位置，再按实际书稿需要选择进入自己书中的结构。实际书稿的结构清单由写作目标、读者任务和发布边界决定；本书展示结构位置和组合关系，不作为必选清单。
+
 日常写作起点可以参考样本 `01-starter-book`。

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

@@ -3,6 +3,8 @@
 
 前置内容用于建立读者进入正文之前需要知道的说明、来源和阅读位置。
 
+方括号中的名称是 section style。它作用于紧随其后的 section；当下一行是 include 指令时，style 作用于被 include 文件中的 section 标题。
+
 [cols="1,2", options="header"]
 |===
 |结构 |职责

package/templates/default-workspace/books/00-book-anatomy/parts/02-body-structure/01-body-map.adoc

@@ -1,13 +1,17 @@
 [#body-map]
 == 正文结构地图
 
-part 是 book doctype 中的 level 0 section。chapter 是 part 下的 level 1 section，也就是 `==` 标题。
+part 是 book doctype 中 document title 之后的 level 0 section。level 1 section 通常形成 chapter；multipart book 中 chapter 位于 part 下，普通 book 中 chapter 可以直接位于 book 下。
+
+本模板把每个 part 的源文件放在 `parts/<part-id>/` 下。这个目录约定服务维护边界；part 本身由 `book.adoc` 中的 level 0 section 声明。
+
+本书启用 `:sectnums:`。part 标题不占用 chapter 编号；part 下的 level 1 section 按 `book.adoc` 展开后的顺序形成连续 chapter 编号。
 
 === 小节层级
 
-小节用于组织 chapter 内部内容。(((section)))
+indexterm2:[section] 是 chapter 内部的层级单位。indexterm:[section, hierarchy]
 
 [discrete]
 === 离散标题
 
-离散标题提供视觉分隔，但不进入书籍目录层级。(((discrete heading)))
+离散标题显示为标题样式，但不创建 section，不参与章节编号，也不进入目录。indexterm:[heading, discrete]

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

@@ -0,0 +1,32 @@
+[#inline-structure-map]
+== 内联结构标记
+
+内联结构标记用于给正文中的术语、路径、引用目标和索引入口提供稳定身份。它不改变 book 的章节层级，但会提高正文片段的可维护性和可检索性。
+
+[cols="1,2", options="header"]
+|===
+|写法 |结构作用
+
+|`[#stable-anchor]`
+|声明稳定引用目标。
+
+|`xref:#body-map[正文结构地图]`
+|引用同一文档内的稳定目标。
+
+|`indexterm2:[term]`
+|把正文中已经出现的词作为可见索引词。
+
+|`indexterm:[term, detail]`
+|正文没有出现该词时，补充隐藏索引入口。
+
+|`[.term]#inline role#`
+|给术语片段提供语义身份。
+
+|`[.path]` + monospace path
+|给路径文本提供语义身份。
+
+|`{series-name}`
+|引用共享属性，减少多处重复文本。
+|===
+
+语义 inline role 提供结构身份；具体视觉效果取决于输出样式。本书使用 [.term]#inline role# 标记术语片段，使用 [.path]`parts/02-body-structure/` 标记路径片段。

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

@@ -0,0 +1,62 @@
+= 附录 A：结构化写法速查
+
+[cols="1,2", options="header"]
+|===
+|写法 |含义
+
+|`= 书名`
+|Document title（文档标题）。在 book 文档类型中作为整本书标题。
+
+|`= 部标题`
+|Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。
+
+|`== 章 / 标题`
+|Level 1 Section（一级章节）。创建书稿阅读结构，在 book 文档类型中通常作为 Chapter（章）。
+
+|`=== 节`
+|Level 2 Section（二级章节 / 节）。
+
+|`==== 小节`
+|Level 3 Section（三级章节 / 小节）。
+
+|`===== 次小节`
+|Level 4 Section（四级章节）。
+
+|`====== 最底层级`
+|Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。
+
+|`parts/100-topic/`
+|part 目录的源文件编排号。
+
+|`010-opening.adoc`
+|chapter 文件的源文件编排号。
+
+|`[#stable-id]`
+|为重要标题声明稳定 ID。
+
+|`[#stable-id.concept]`
+|声明稳定 ID，并用 role 标明标题身份。
+
+|`[#example.example, owner=writing-team]`
+|role 声明标题身份；named attributes 保留附加字段。
+
+|`xref:stable-id[显示文本]`
+|显示为链接，投影为 references。
+
+|`xref:stable-id[显示文本, rel=depends-on]`
+|显示为链接，同时声明 depends-on 关系。
+
+|`indexterm2:[role]`
+|正文可见索引词。
+
+|`indexterm:[relation predicate]`
+|正文隐藏索引词。
+|===
+
+role 描述标题身份。rel 描述 xref 边上的关系谓词。named attributes 是附加字段。
+
+`[appendix]`、`[glossary]`、`[bibliography]` 和 `[index]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
+
+对于跨文件的交叉引用，为了避免重复编写相对路径，你可以在文档的头部（Header）定义一个文档属性（Document Attribute）来存储这个基础路径。
+
+你可以在主文档的开头定义一个变量（比如 `:book-b-dir:`），后续引用时通过 `{book-b-dir}` 来调用它。

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/bibliography.adoc

@@ -0,0 +1,7 @@
+= 参考坐标
+
+以下资料提供 AsciiDoc 标题、交叉引用和元素属性的参考坐标。
+
+* [[[asciidoctor-xref]]] Asciidoctor Docs, Cross References, https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
+* [[[asciidoctor-attributes]]] Asciidoctor Docs, Element Attributes, https://docs.asciidoctor.org/asciidoc/latest/attributes/element-attributes/
+* [[[asciidoctor-sections]]] Asciidoctor Docs, Sections, https://docs.asciidoctor.org/asciidoc/latest/sections/

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/glossary.adoc

@@ -0,0 +1,14 @@
+= 术语表
+
+本术语表记录结构化书写约定中的核心术语。
+
+heading:: 使用等号标题创建的书稿结构单位。
+stable ID:: 作者声明的稳定引用地址，例如 `#stable-heading`。
+source-order notation:: 写在源文件路径表面的排序符号。
+role:: 标题身份标记，例如 `.concept` 或 `.rule`。
+ordinary reference:: 普通 xref。投影时使用默认谓词 `aat:references`。
+relation predicate:: xref `rel` 字段选择的边谓词。
+source heading:: xref 所在的标题。
+target heading:: xref selector 指向的标题。
+surface field:: named attributes 携带的源文档表面字段。
+index term:: 服务书后索引和读者检索的索引入口。

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/index.adoc

@@ -0,0 +1,37 @@
+= 索引
+
+索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源。
+
+AsciiDoc 区分正文可见索引词和正文隐藏索引词：
+
+[cols="1,2", options="header"]
+|===
+|写法 |含义
+
+|`indexterm2:[<primary>]`
+|正文可见，同时作为一级索引项。
+
+|`indexterm:[<primary>]`
+|正文不可见，作为一级索引项。
+
+|`indexterm:[<primary>, <secondary>]`
+|正文不可见，作为二级索引项。
+
+|`indexterm:[<primary>, <secondary>, <tertiary>]`
+|正文不可见，作为三级索引项。
+|===
+
+正文中已经出现该词时，优先使用正文可见索引词。需要补充未出现在正文里的索引入口时，使用正文隐藏索引词。
+
+隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾。
+
+Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。`[index]` section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。
+
+本书正文中的索引词示例：
+
+[source,asciidoc]
+----
+indexterm2:[role]
+indexterm:[relation predicate]
+indexterm:[源文件编排号]
+----

package/templates/default-workspace/books/07-structured-writing-conventions/book.adoc

@@ -0,0 +1,71 @@
+= 结构化书写约定标本
+作者 <author@example.com>
+v0.1, 2026-05
+:doctype: book
+:toc: left
+:toclevels: 3
+:sectnums:
+:partnums:
+:part-signifier: Part
+:icons: font
+:experimental:
+:idprefix:
+:idseparator: -
+
+include::../../shared/attributes.adoc[]
+
+[abstract]
+include::frontmatter/abstract.adoc[]
+
+[colophon]
+include::frontmatter/colophon.adoc[]
+
+[dedication]
+include::frontmatter/dedication.adoc[]
+
+[preface]
+include::frontmatter/preface.adoc[]
+
+[acknowledgments]
+include::frontmatter/acknowledgments.adoc[]
+
+= 从源文档看结构
+
+[partintro]
+include::parts/100-source-surface/_partintro.adoc[]
+
+include::parts/100-source-surface/010-source-and-projection.adoc[]
+
+include::parts/100-source-surface/020-default-semantics.adoc[]
+
+include::parts/100-source-surface/030-source-order-notation.adoc[]
+
+= 给标题和引用加意图
+
+[partintro]
+include::parts/200-identity-and-relation/_partintro.adoc[]
+
+include::parts/200-identity-and-relation/010-role-identity.adoc[]
+
+include::parts/200-identity-and-relation/020-relation-predicate.adoc[]
+
+= 字段、索引与术语
+
+[partintro]
+include::parts/300-fields-and-lookup/_partintro.adoc[]
+
+include::parts/300-fields-and-lookup/010-surface-fields.adoc[]
+
+include::parts/300-fields-and-lookup/020-index-and-glossary.adoc[]
+
+[appendix]
+include::backmatter/appendix-a.adoc[]
+
+[glossary]
+include::backmatter/glossary.adoc[]
+
+[bibliography]
+include::backmatter/bibliography.adoc[]
+
+[index]
+include::backmatter/index.adoc[]

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/abstract.adoc

@@ -0,0 +1,3 @@
+== 摘要
+
+本书会通过展示标题、稳定 ID、role、xref、rel 和 named attributes 如何形成可读、可维护、可投影的源文档，让你能够理解，你可以有这样一种表达方式，按照某种约定，能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考你当前写书所需要的结构，合适的结构能够提升书籍的可阅读，可维护性。你可以按写作目的选择其中写法。

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/acknowledgments.adoc

@@ -0,0 +1,3 @@
+== 致谢
+
+感谢 Asciidoctor 和 RDF 投影相关文档提供稳定术语和结构坐标。

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/colophon.adoc

@@ -0,0 +1,5 @@
+== 版本说明
+
+本文档属于 `{series-name}`。colophon 位于书籍前置区域，记录本样本书的版本、来源或出版信息。
+
+示例版本：v0.1。

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/dedication.adoc

@@ -0,0 +1,3 @@
+== 献辞
+
+献给每一位愿意为自己写下的标题、引用和标记负责的作者。

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/preface.adoc

@@ -0,0 +1,7 @@
+== 前言
+
+这本标本书按源文档写法组织。阅读时先看源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。
+
+实际书稿按写作目的选择这些写法。长期引用的标题使用稳定 ID；带有明确身份的标题使用 role；表达关系的引用使用 rel；随源稿保留的字段使用 named attributes。
+
+业务含义由书稿自己的约定承载。本书展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/010-source-and-projection.adoc

@@ -0,0 +1,44 @@
+[#source-and-projection]
+== 源文本与投影
+
+本章用一段示例展示结构化书写约定。Turtle 片段列出关键投影事实；完整投影还会保留 raw、路径、行号和边证据。
+希望你能通过本章节的演示来理解你写下的文字能够给未来的你提供稳定的查询与导航结构。
+
+[source,asciidoc]
+----
+= 结构化写作样例
+
+[#stable-heading.concept]
+== 稳定标题
+
+稳定标题提供可引用的阅读单位。
+
+[#xref-rule.rule]
+== 引用规则
+
+引用规则参见 xref:stable-heading[稳定标题]。
+引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on, weight=strong]。
+----
+
+源文档把 `稳定标题` 写成可引用的阅读单位，把 `引用规则` 写成规则说明，并在正文里写出参见和依赖两种引用。
+
+[source,turtle]
+----
+:stable-heading a aat:Heading ;
+  aat:headline "稳定标题" ;
+  aat:addressLabel "stable-heading" ;
+  aat:role "concept" .
+
+:xref-rule a aat:Heading ;
+  aat:headline "引用规则" ;
+  aat:addressLabel "xref-rule" ;
+  aat:role "rule" ;
+  aat:references :stable-heading ;
+  rel:depends-on :stable-heading .
+
+:xref-edge-depends-on a aat:XrefEdge ;
+  aat:rel "depends-on" ;
+  aat:weight "strong" .
+----
+
+读者看源文档，能直接看到 [.concept]#稳定标题# 是被引用的阅读单位， [.rule]#引用规则# 说明引用写法。下游投影工具链读取同一份源文档，得到 `aat:Heading`、`aat:addressLabel`、`aat:role`、`aat:references` 和 `rel:depends-on`。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/020-default-semantics.adoc

@@ -0,0 +1,26 @@
+[#heading-and-xref]
+== 标题与引用
+
+等号行是标题。标题前一行的 attrlist 承载地址和 role。
+
+[source,asciidoc]
+----
+[#stable-heading.concept]
+== 稳定标题
+----
+
+`#stable-heading` 给标题一个稳定地址；`.concept` 标明标题身份；`稳定标题` 是读者看到的标题文本。
+
+[source,asciidoc]
+----
+引用规则参见 xref:stable-heading[稳定标题]。
+----
+
+这条 xref 表示参见目标标题。投影时，这条引用使用默认谓词 `aat:references`。
+
+[source,asciidoc]
+----
+引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。
+----
+
+写入 `rel=depends-on` 时，作者声明当前标题到目标标题的依赖关系。投影时，这条关系使用 `rel:depends-on`。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/030-source-order-notation.adoc

@@ -0,0 +1,23 @@
+[#source-order-notation]
+== 源文件编排号
+
+源文件编排号写在 part 目录名和 chapter 文件名前部。indexterm:[源文件编排号]
+
+part 目录使用 `100-`、`200-`、`300-`。chapter 文件在所属 part 内使用 `010-`、`020-`、`030-`。
+
+中间插入新文件时，使用相邻编号之间的空位。
+
+[source,text]
+----
+parts/100-source-surface/
+parts/150-new-topic/
+parts/200-identity-and-relation/
+
+010-opening.adoc
+015-new-context.adoc
+020-main-flow.adoc
+----
+
+标题文本保留语义名称。长期引用的标题使用显式 ID。
+
+编排号帮助维护者观察源文件顺序；显式 ID 帮助读者和工具链稳定引用标题。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/_partintro.adoc

@@ -0,0 +1 @@
+本部从一段源文档出发，展示读者看到的写作意图和投影得到的结构事实。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/200-identity-and-relation/010-role-identity.adoc

@@ -0,0 +1,37 @@
+[#role-identity]
+== role 身份
+
+`[#xref-rule.rule]` 里的 `.rule` 是 indexterm2:[role]。它把这个标题标成规则说明。
+
+role 写在标题 attrlist 的点号 token 位置。
+
+[source,asciidoc]
+----
+[#stable-heading.concept]
+== 稳定标题
+
+[#xref-rule.rule]
+== 引用规则
+----
+
+`#stable-heading` 和 `#xref-rule` 是稳定 ID。`.concept` 和 `.rule` 标明标题身份。
+
+[cols="1,2", options="header"]
+|===
+|写法 |读者看到的身份
+
+|`[.concept]`
+|标记概念说明。
+
+|`[.rule]`
+|标记规则说明。
+
+|`[.example]`
+|标记示例。
+|===
+
+role 的职责，是在全书范围内保持身份含义的稳定。
+
+一旦一个 role 被定义——例如 `.rule` 代表规则说明——它在全书任何地方都只能代表这个身份，不能产生歧义。一本书需要多少种 role，取决于它所要描述的领域固有的本质复杂度。无论三种还是十种，每一种都必须是确定的。
+
+读者和工具链依赖这种稳定理解来导航文本和提取结构。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/200-identity-and-relation/020-relation-predicate.adoc

@@ -0,0 +1,22 @@
+[#relation-predicate]
+== rel 关系谓词
+
+indexterm:[relation predicate] `rel` 是 xref 边上的关系谓词。xref 写在哪个标题下面，哪个标题就是关系起点；xref 指向哪个标题，哪个标题就是关系终点。本书把这两个位置称为 source heading 和 target heading。
+
+[source,asciidoc]
+----
+引用规则参见 xref:stable-heading[稳定标题]。
+引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。
+----
+
+第一行表示参见 `稳定标题`，投影为 `aat:references`。第二行写入 `rel=depends-on`，声明 `引用规则` 到 `稳定标题` 的依赖关系，投影为 `rel:depends-on`。
+
+`rel` 会被读者和工具当作关系谓词。同一本书使用 rel 时，应保持谓词含义稳定。
+
+[horizontal]
+depends-on:: 当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。
+illustrates:: 当前标题提供目标标题的示例。
+defines:: 当前标题给出目标标题所代表对象的定义。
+constrains:: 当前标题对目标标题的合法写法或范围施加约束。
+
+关系谓词描述标题之间的边。标题自身的身份使用 role 表达。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/200-identity-and-relation/_partintro.adoc

@@ -0,0 +1 @@
+本部展示标题身份和引用关系。role 标明标题身份；rel 标明引用关系。 你应该在自己书籍里增加各类词表约定的章节。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/300-fields-and-lookup/010-surface-fields.adoc

@@ -0,0 +1,18 @@
+[#surface-fields]
+== 附加字段
+
+named attributes 是写在源文档表面的字段。
+
+[source,asciidoc]
+----
+[#example.example, owner=writing-team]
+== 示例
+
+示例说明 xref:stable-heading[稳定标题, rel=illustrates, weight=strong]。
+----
+
+`.example` 是 role。`owner=writing-team` 是标题附加字段。`weight=strong` 是 xref 边证据上的附加字段。
+
+`owner=writing-team` 写在标题 attrlist 中，投影时成为标题字段。`weight=strong` 写在 xref 中，投影时成为边证据字段。
+
+字段名和字段值来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/300-fields-and-lookup/020-index-and-glossary.adoc

@@ -0,0 +1,14 @@
+[#index-and-glossary]
+== 索引词与术语表
+
+索引词帮助读者在书后找到词。术语表解释本书采用的词。role 标明标题身份，rel 标明引用关系。
+
+正文里已经自然出现该词时，使用可见索引词标记。需要补充未出现在正文里的索引入口时，使用隐藏索引词。
+
+[source,asciidoc]
+----
+indexterm2:[role]
+indexterm:[relation predicate]
+----
+
+稳定术语帮助作者、读者和维护者使用同一组词理解源文档。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/300-fields-and-lookup/_partintro.adoc

@@ -0,0 +1 @@
+本部展示字段、索引词和术语表。字段随源文档保留；索引词和术语表帮助读者找词、解词。

package/templates/default-workspace/catalog.adoc

@@ -43,6 +43,10 @@ v0.1, 2026-05
 |组织可独立发布的下册
 |xref:books/06-lower-volume/book.adoc[06 下册]
 |它用文本示例说明跨卷引用写法，但不真实依赖上册。
+
+|让源书稿保持可读，同时保留可被工具链读取的结构关系
+|xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]
+|它展示标题、稳定 ID、role、xref、rel 和附加字段如何形成结构化书稿表面。
 |===
 
 == 样本书
@@ -54,6 +58,7 @@ v0.1, 2026-05
 * xref:books/04-reference-manual/book.adoc[04 参考手册]：结构选择、路径规则和引用模式。
 * xref:books/05-upper-volume/book.adoc[05 上册]：独立分卷的上册。
 * xref:books/06-lower-volume/book.adoc[06 下册]：独立分卷的下册，并用示例说明跨卷引用写法。
+* xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]：标题、稳定 ID、role、xref、rel 和附加字段的结构化写法。
 
 == 工作区地图
 
@@ -66,3 +71,4 @@ image::shared/images/workspace-map.svg[多书工作区结构]
 * 下册需要说明跨卷引用写法但不制造默认依赖：看 xref:books/06-lower-volume/book.adoc[06 下册]。
 * 新增一本普通书：从 xref:books/01-starter-book/book.adoc[01 日常独立单书] 开始。
 * 查路径、引用和增长规则：看 xref:books/04-reference-manual/book.adoc[04 参考手册]。
+* 写需要被读者和工具同时理解的结构化源文本：看 xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]。