create-asciidoc-multi-book-workspace 0.1.0

package/dist/runtime/adoc-books.mjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+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";
+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 SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+const HOME_MARKER = "data-multi-book-home";
+const FETCH_DIAGRAMS_ENV = "ADOC_BOOKS_FETCH_DIAGRAMS";
+async function existsFile(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function existsDir(dir) {
+    try {
+        const stats = await stat(dir);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function collectFiles(dir, predicate) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await collectFiles(entryPath, predicate));
+        }
+        else if (entry.isFile() && predicate(entryPath)) {
+            files.push(entryPath);
+        }
+    }
+    return files.sort();
+}
+async function discoverBooks(rootDir) {
+    const booksDir = path.join(rootDir, "books");
+    const entries = await readdir(booksDir, { withFileTypes: true });
+    const books = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const bookDir = path.join(booksDir, entry.name);
+        const input = path.join(bookDir, "book.adoc");
+        if (await existsFile(input)) {
+            books.push({
+                bookId: entry.name,
+                bookDir,
+                input,
+                htmlOutputDir: path.join(rootDir, "build", "html", "books", entry.name)
+            });
+        }
+    }
+    return books.sort((a, b) => a.bookId.localeCompare(b.bookId));
+}
+async function readIfExists(filePath) {
+    return await existsFile(filePath) ? readFile(filePath, "utf8") : "";
+}
+async function combinedBookSource(bookDir) {
+    const files = await collectFiles(bookDir, (filePath) => filePath.endsWith(".adoc"));
+    const sources = [];
+    for (const file of files)
+        sources.push(await readFile(file, "utf8"));
+    return sources.join("\n");
+}
+async function workspaceUsesDiagrams(rootDir, books) {
+    const sources = [await readIfExists(path.join(rootDir, "catalog.adoc"))];
+    for (const book of books)
+        sources.push(await combinedBookSource(book.bookDir));
+    return sources.some((source) => DIAGRAM_BLOCK_PATTERN.test(source));
+}
+function createAsciidoctor(loadKroki) {
+    const asciidoctor = require("asciidoctor")();
+    require("@asciidoctor/reducer").register();
+    if (loadKroki) {
+        try {
+            require("asciidoctor-kroki").register(asciidoctor.Extensions);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`current workspace contains diagram blocks, but asciidoctor-kroki could not be loaded: ${message}`);
+        }
+    }
+    return asciidoctor;
+}
+function shouldFetchDiagrams() {
+    const value = process.env[FETCH_DIAGRAMS_ENV];
+    return value === "1" || value === "true";
+}
+function reduceAdocSource(asciidoctor, input) {
+    const doc = asciidoctor.loadFile(input, { safe: "unsafe" });
+    const source = doc.getSource();
+    if (/^[ \t]*include::/m.test(source)) {
+        throw new Error(`reducer left unresolved include directives in ${input}`);
+    }
+    return source;
+}
+async function buildReducedAdoc(rootDir, books, asciidoctor) {
+    const adocDir = path.join(rootDir, "build", "adoc");
+    await rm(adocDir, { force: true, recursive: true });
+    await mkdir(path.join(adocDir, "books"), { recursive: true });
+    const catalogSource = reduceAdocSource(asciidoctor, path.join(rootDir, "catalog.adoc"));
+    await writeFile(path.join(adocDir, "catalog.adoc"), catalogSource, "utf8");
+    for (const book of books) {
+        const source = reduceAdocSource(asciidoctor, book.input);
+        await writeFile(path.join(adocDir, "books", `${book.bookId}.adoc`), source, "utf8");
+    }
+}
+async function pruneStaleBookHtmlDirs(rootDir, books) {
+    const htmlBooksDir = path.join(rootDir, "build", "html", "books");
+    if (!await existsDir(htmlBooksDir))
+        return;
+    const current = new Set(books.map((book) => book.bookId));
+    const entries = await readdir(htmlBooksDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory() && !current.has(entry.name)) {
+            await rm(path.join(htmlBooksDir, entry.name), { force: true, recursive: true });
+        }
+    }
+}
+function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
+    asciidoctor.convertFile(input, {
+        safe: "unsafe",
+        base_dir: baseDir,
+        to_file: outputFile,
+        mkdirs: true,
+        attributes
+    });
+}
+async function buildHtml(rootDir, books, asciidoctor, 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);
+    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, {
+            ...(useKroki && fetchDiagrams ? { "kroki-fetch-diagram": "", "kroki-http-method": "post" } : {})
+        });
+    }
+}
+async function copyAssets(rootDir, books) {
+    const sharedImages = path.join(rootDir, "shared", "images");
+    if (await existsDir(sharedImages)) {
+        await rm(path.join(rootDir, "build", "html", "shared", "images"), { force: true, recursive: true });
+        await cp(sharedImages, path.join(rootDir, "build", "html", "shared", "images"), { recursive: true });
+    }
+    for (const book of books) {
+        const assetsDir = path.join(book.bookDir, "assets");
+        if (await existsDir(assetsDir)) {
+            await rm(path.join(book.htmlOutputDir, "assets"), { force: true, recursive: true });
+            await cp(assetsDir, path.join(book.htmlOutputDir, "assets"), { recursive: true });
+        }
+    }
+}
+function escapeHtmlAttribute(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll('"', """)
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function addHomeLinkToBookHtml(html, href) {
+    if (html.includes(HOME_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 = `
+<style>
+.multi-book-home {
+  margin: 0 0 1rem;
+  padding-bottom: .75rem;
+  border-bottom: 1px solid #e5e7eb;
+}
+.multi-book-home a {
+  color: #1f2937;
+  display: block;
+  font-weight: 600;
+  line-height: 1.35;
+  text-decoration: none;
+}
+.multi-book-home a:hover {
+  color: #0f766e;
+  text-decoration: underline;
+}
+.multi-book-home span {
+  color: #64748b;
+  display: block;
+  font-size: .78rem;
+  font-weight: 400;
+  margin-top: .15rem;
+}
+</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)}`;
+}
+async function addHomeLinks(rootDir, books) {
+    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");
+    }
+}
+async function writeRootIndex(rootDir) {
+    const outputDir = path.join(rootDir, "build", "html");
+    await mkdir(outputDir, { recursive: true });
+    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>
+</head>
+<body>
+  <p><a href="catalog.html">catalog.html</a></p>
+</body>
+</html>
+`, "utf8");
+}
+function extractCatalogBookIds(catalogSource) {
+    const ids = new Set();
+    for (const match of catalogSource.matchAll(CATALOG_BOOK_XREF_PATTERN))
+        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 };
+}
+async function workspaceContractIssues(rootDir, books) {
+    const issues = [];
+    const catalogSource = await readIfExists(path.join(rootDir, "catalog.adoc"));
+    const catalogBookIds = extractCatalogBookIds(catalogSource);
+    const bookSet = new Set(books.map((book) => book.bookId));
+    const catalogBookSet = new Set(catalogBookIds);
+    for (const bookId of catalogBookIds) {
+        if (!bookSet.has(bookId))
+            issues.push(issue("CATALOG_TARGET_MISSING", bookId));
+    }
+    for (const book of books) {
+        if (!catalogBookSet.has(book.bookId))
+            issues.push(issue("BOOK_MISSING_FROM_CATALOG", book.bookId));
+    }
+    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;
+}
+async function collectHtmlFiles(dir) {
+    return collectFiles(dir, (filePath) => filePath.endsWith(".html"));
+}
+function extractLocalTargets(html) {
+    const targets = [];
+    for (const match of html.matchAll(LOCAL_TARGET_PATTERN)) {
+        const rawTarget = match[1];
+        if (rawTarget === "" || rawTarget.startsWith("#") || rawTarget.startsWith("//") || SCHEME_PATTERN.test(rawTarget)) {
+            continue;
+        }
+        const targetWithoutFragment = rawTarget.split("#", 1)[0].split("?", 1)[0];
+        if (targetWithoutFragment !== "")
+            targets.push(rawTarget);
+    }
+    return targets;
+}
+async function missingLocalResources(rootDir) {
+    const htmlDir = path.join(rootDir, "build", "html");
+    const htmlFiles = await collectHtmlFiles(htmlDir);
+    const issues = [];
+    for (const htmlFile of htmlFiles) {
+        const html = await readFile(htmlFile, "utf8");
+        for (const target of extractLocalTargets(html)) {
+            const targetPath = target.split("#", 1)[0].split("?", 1)[0];
+            const resolved = path.resolve(path.dirname(htmlFile), targetPath);
+            if (!await existsFile(resolved)) {
+                issues.push(issue("HTML_RESOURCE_MISSING", `${path.relative(htmlDir, htmlFile)} -> ${target}`));
+            }
+        }
+    }
+    return issues;
+}
+async function assertNoIssues(label, issues) {
+    if (issues.length === 0)
+        return;
+    for (const entry of issues)
+        console.error(`${entry.code}: ${entry.detail}`);
+    throw new Error(`${label} failed with ${issues.length} issue(s)`);
+}
+export async function buildWorkspace(rootDir = process.cwd()) {
+    const catalog = path.join(rootDir, "catalog.adoc");
+    if (!await existsFile(catalog))
+        throw new Error(`missing catalog.adoc in ${rootDir}`);
+    const books = await discoverBooks(rootDir);
+    if (books.length === 0)
+        throw new Error(`missing book.adoc entries in ${path.join(rootDir, "books")}`);
+    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 assertNoIssues("HTML local resource check", await missingLocalResources(rootDir));
+    await assertNoIssues("workspace contract check", await workspaceContractIssues(rootDir, books));
+}
+export async function checkWorkspace(rootDir = process.cwd()) {
+    await buildWorkspace(rootDir);
+}
+export async function cleanWorkspace(rootDir = process.cwd()) {
+    await rm(path.join(rootDir, "build"), { force: true, recursive: true });
+}
+async function main() {
+    const command = process.argv[2];
+    if (command === "build") {
+        await buildWorkspace();
+        return;
+    }
+    if (command === "check") {
+        await checkWorkspace();
+        return;
+    }
+    if (command === "clean") {
+        await cleanWorkspace();
+        return;
+    }
+    console.error("Usage: node tools/adoc-books.mjs <build|check|clean>");
+    process.exitCode = 1;
+}
+const executedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
+const modulePath = fileURLToPath(import.meta.url);
+if (executedPath === modulePath) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}

package/dist/template-manifest.js

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "create-asciidoc-multi-book-workspace",
+  "version": "0.1.0",
+  "description": "Create a complete AsciiDoc multi-book workspace.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "弥澄亮",
+    "email": "t103ooooo@stu.mju.edu.cn",
+    "url": "https://github.com/MichengLiang"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichengLiang/asciidoc-multi-book-workspace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MichengLiang/asciidoc-multi-book-workspace/issues"
+  },
+  "homepage": "https://michengliang.github.io/asciidoc-multi-book-workspace/",
+  "type": "module",
+  "keywords": [
+    "asciidoc",
+    "asciidoctor",
+    "books",
+    "create",
+    "initializer",
+    "multi-book"
+  ],
+  "bin": {
+    "create-asciidoc-multi-book-workspace": "dist/create.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@asciidoctor/reducer": "1.1.2",
+    "@types/node": "24.10.1",
+    "asciidoctor": "2.2.9",
+    "asciidoctor-kroki": "0.18.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "pack:check": "pnpm pack --dry-run",
+    "check": "pnpm run test && pnpm run pack:check",
+    "clean": "rm -rf dist build"
+  }
+}

package/templates/default-workspace/README.md

@@ -0,0 +1,66 @@
+# 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.
+
+## Install
+
+```bash
+pnpm install
+```
+
+## Build
+
+```bash
+pnpm run build
+```
+
+Outputs:
+
+- `build/html/index.html`
+- `build/html/catalog.html`
+- `build/html/books/<book-id>/book.html`
+- `build/adoc/catalog.adoc`
+- `build/adoc/books/<book-id>.adoc`
+
+Diagram blocks render as Kroki image URLs by default, so normal builds do not depend on the Kroki service being available at build time.
+To fetch diagram images into the local HTML output, run:
+
+```bash
+ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
+```
+
+## Check
+
+```bash
+pnpm run check
+```
+
+This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources.
+
+## Clean
+
+```bash
+pnpm run clean
+```
+
+This removes `build/`.
+
+## Delete Sample Books
+
+Delete `books/<book-id>/`, then remove the matching `xref:books/<book-id>/book.adoc[...]` entry from `catalog.adoc`. Each default sample is independent, so no other sample book needs to be edited.
+
+Run:
+
+```bash
+pnpm run check
+```
+
+## Add A Book
+
+Copy `books/01-starter-book` to `books/<your-book-id>`, edit `book.adoc` and chapter files, then add the new book to `catalog.adoc`.
+
+To look at the original samples again, initialize a temporary workspace:
+
+```bash
+pnpm create asciidoc-multi-book-workspace sample-look
+```

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

@@ -0,0 +1,18 @@
+= 附录 A：结构速查
+
+[cols="1,2", options="header"]
+|===
+|写法 |含义
+
+|`= 书名`
+|document title。
+
+|`= 第一部`
+|book doctype 中的 part。
+
+|`== 章`
+|chapter。
+
+|`=== 节`
+|section。
+|===

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

@@ -0,0 +1,4 @@
+= 参考资料
+
+* [[[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

@@ -0,0 +1,10 @@
+= 术语表
+
+book:: 具有独立 `book.adoc`、章节顺序和构建产物的书籍单位。
+part:: 同一本 book 内部的 level 0 大分部。
+chapter:: book 中的主要正文单位，通常使用 `==` 标题。
+section:: chapter 内部的层级标题。
+appendix:: 放置补充材料的后置章节。
+glossary:: 使用定义列表解释术语的后置章节。
+bibliography:: 放置参考资料的后置章节。
+index:: 放置索引入口的后置章节。

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

@@ -0,0 +1,9 @@
+= 索引
+
+索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源：
+
+[source,asciidoc]
+----
+(((section)))
+(((discrete heading)))
+----

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

@@ -0,0 +1,54 @@
+= 完整书籍结构标本
+作者 <author@example.com>
+v0.1, 2026-05
+:doctype: book
+:toc: left
+:toclevels: 3
+:sectnums:
+: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/01-front-structure/_partintro.adoc[]
+
+include::parts/01-front-structure/01-frontmatter-map.adoc[]
+
+= 第二部：正文结构
+
+[partintro]
+include::parts/02-body-structure/_partintro.adoc[]
+
+include::parts/02-body-structure/01-body-map.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/00-book-anatomy/frontmatter/abstract.adoc

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

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

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

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

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

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

@@ -0,0 +1,3 @@
+== 献辞
+
+献给每一位需要把书稿结构先想清楚再开始写作的人。

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

@@ -0,0 +1,5 @@
+== 前言
+
+这本标本书按结构位置组织，而不是按主题展开。阅读时先看 `book.adoc`，再对照各个被 include 的文件。
+
+日常写作起点可以参考样本 `01-starter-book`。

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

@@ -0,0 +1,24 @@
+[#frontmatter-map]
+== 前置内容地图
+
+前置内容用于建立读者进入正文之前需要知道的说明、来源和阅读位置。
+
+[cols="1,2", options="header"]
+|===
+|结构 |职责
+
+|`[abstract]`
+|说明整本书覆盖什么。
+
+|`[colophon]`
+|记录版本、出版或来源信息。
+
+|`[dedication]`
+|放置献辞。
+
+|`[preface]`
+|说明写作目的和阅读方式。
+
+|`[acknowledgments]`
+|放置致谢。
+|===