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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.1 - 2026-06-06
+
+### Added
+
+- Add maintainer preview commands for rebuilding the default sample workspace locally.
+- Keep routine template previews fast by using the maintainer AsciiDoc toolchain, while `preview:fresh` still verifies the generated workspace's own dependency installation.
+
+### Changed
+
+- Use `build/template-preview/workspace/build/html/index.html` as the single preview HTML output path.
+- Keep preview source and tests out of the npm package boundary while publishing the compiled script referenced by maintainer commands.
+
 ## 0.1.0 - 2026-06-04
 
 ### Added

package/README.md

@@ -19,6 +19,10 @@ npm users can run:
 npm create asciidoc-multi-book-workspace@latest my-books
 ```
 
+```bash
+npx create-asciidoc-multi-book-workspace@latest my-books
+```
+
 The generated workspace contains:
 
 ```text
@@ -75,6 +79,8 @@ The seven sample books live only under `templates/default-workspace/books/`.
 ```bash
 pnpm install
 pnpm run build
+pnpm run preview:build
+pnpm run preview:fresh
 pnpm run test
 pnpm run check
 pnpm pack --dry-run
@@ -82,6 +88,14 @@ pnpm pack --dry-run
 
 `pnpm run check` builds TypeScript, runs maintainer tests, and checks the npm package boundary.
 
+`pnpm run preview:build` updates a generated sample workspace under `build/template-preview/workspace`,
+builds the sample books with the maintainer repository's installed AsciiDoc toolchain, and writes HTML to
+`build/template-preview/workspace/build/html/index.html`.
+
+`pnpm run preview:fresh` recompiles the maintainer runtime and recreates the preview workspace from scratch.
+It installs the generated workspace's own dependencies, so use it after changing `src/`, dependency declarations,
+or the initializer contract. Use `pnpm run preview:build` for normal template edits under `templates/default-workspace/`.
+
 ## Releases
 
 Release Please manages release pull requests and `CHANGELOG.md`.

package/dist/build-template-preview.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { initWorkspace } from "./init-workspace.js";
+const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(sourceDir, "..");
+const defaultPreviewRoot = path.join(packageRoot, "build", "template-preview");
+const templateWorkspacePaths = ["README.md", "catalog.adoc", "package.json", ".gitignore", "books", "shared", "tools"];
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultRunCommand(command, args, options) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            shell: process.platform === "win32",
+            stdio: "inherit"
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${command} ${args.join(" ")} exited with code ${code ?? "unknown"}`));
+        });
+    });
+}
+export async function buildTemplatePreview(options = {}) {
+    const previewRoot = path.resolve(options.previewRoot ?? defaultPreviewRoot);
+    const workspaceDir = path.join(previewRoot, "workspace");
+    const htmlDir = path.join(workspaceDir, "build", "html");
+    const legacyHtmlMirrorDir = path.join(previewRoot, "html");
+    const installStamp = path.join(previewRoot, ".installed-package.json");
+    const runCommand = options.runCommand ?? defaultRunCommand;
+    const installDependencies = options.install === true || options.fresh === true;
+    if (options.fresh)
+        await rm(previewRoot, { force: true, recursive: true });
+    await mkdir(previewRoot, { recursive: true });
+    await mkdir(workspaceDir, { recursive: true });
+    for (const name of templateWorkspacePaths) {
+        await rm(path.join(workspaceDir, name), { force: true, recursive: true });
+    }
+    await initWorkspace({ targetDir: workspaceDir, force: true });
+    if (installDependencies) {
+        const packageJson = await readFile(path.join(workspaceDir, "package.json"), "utf8");
+        const installedPackageJson = await exists(installStamp) ? await readFile(installStamp, "utf8") : "";
+        if (!await exists(path.join(workspaceDir, "node_modules")) ||
+            !await exists(path.join(workspaceDir, "pnpm-lock.yaml")) ||
+            installedPackageJson !== packageJson) {
+            await runCommand("pnpm", ["install", "--ignore-workspace"], { cwd: workspaceDir });
+            await writeFile(installStamp, packageJson, "utf8");
+        }
+    }
+    if (installDependencies) {
+        await runCommand("pnpm", ["run", "build"], { cwd: workspaceDir });
+    }
+    else {
+        await runCommand("node", ["tools/adoc-books.mjs", "build"], { cwd: workspaceDir });
+    }
+    await rm(legacyHtmlMirrorDir, { force: true, recursive: true });
+    return { previewRoot, workspaceDir, htmlDir };
+}
+async function main() {
+    const fresh = process.argv.includes("--fresh");
+    const result = await buildTemplatePreview({
+        fresh,
+        install: fresh || process.argv.includes("--install")
+    });
+    const displayIndex = path.relative(process.cwd(), path.join(result.htmlDir, "index.html")) || "index.html";
+    console.log(`Built template preview at ${displayIndex}`);
+}
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -29,7 +29,11 @@
     "create-asciidoc-multi-book-workspace": "dist/create.js"
   },
   "files": [
-    "dist/",
+    "dist/build-template-preview.js",
+    "dist/create.js",
+    "dist/init-workspace.js",
+    "dist/runtime/adoc-books.mjs",
+    "dist/template-manifest.js",
     "templates/",
     "README.md",
     "CHANGELOG.md",
@@ -47,6 +51,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "preview:build": "node dist/build-template-preview.js",
+    "preview:fresh": "pnpm run build && node dist/build-template-preview.js --fresh",
     "test": "pnpm run build && node --test test/*.test.mjs",
     "pack:check": "pnpm pack --dry-run",
     "check": "pnpm run test && pnpm run pack:check",

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

@@ -4,15 +4,21 @@
 |===
 |写法 |含义
 
-|`= 书名`
-|document title。
-
-|`= 第一部`
-|book doctype 中的 part。
+|`= 书名或文档名`
+|Document title（文档标题，Level 0）。在 book 文档类型中也可作为 Part（部）。
 
 |`== 章`
-|chapter。
+|Level 1 Section（一级章节）。在 book 文档类型中通常作为 Chapter（章）。
 
 |`=== 节`
-|section。
+|Level 2 Section（二级章节 / 节）。
+
+|`==== 小节`
+|Level 3 Section（三级章节 / 小节）。
+
+|`===== 次小节`
+|Level 4 Section（四级章节）。
+
+|`====== 最底层级`
+|Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。
 |===