hd-garden 0.8.0 → 0.8.2

package/scripts/build-content.mjs

@@ -35,6 +35,14 @@ import { trailingSlashEnabled, withTrailingSlash } from "../ui/garden/site-href.
 
 const gardenPackageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
+/** Column status is a framework enum. Older sites wrote the Chinese label, so map those too. */
+const COLUMN_STATUS = { ongoing: "ongoing", completed: "completed", default: "default", 持续更新: "default", 连载中: "ongoing", 更新中: "ongoing", 已完结: "completed", 完结: "completed" };
+function columnStatusOf(raw) {
+  if (raw === undefined) return "default";
+  const key = raw.trim().toLowerCase();
+  return Object.hasOwn(COLUMN_STATUS, key) ? COLUMN_STATUS[key] : raw.trim();
+}
+
 function resolveSiteRoot() {
   if (process.env.GARDEN_SITE) return path.resolve(process.env.GARDEN_SITE);
   const yaml = path.join(process.cwd(), "site.config.yaml");
@@ -56,6 +64,9 @@ const includeDrafts = process.env.CONTENT_INCLUDE_DRAFTS === "1";
 const uiMode = includeDrafts || process.env.GARDEN_CONTENT_MODE === "preview" ? "preview" : "publish";
 const now = Date.now();
 const basePath = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/u, "");
+let previewIconCache;
+/** The site's base-path-aware icon for file previews, so they never fall back to /favicon.ico. */
+const previewIcon = () => (previewIconCache ??= resolveBrand(root, siteConfig, basePath, () => {}).favicon ?? "");
 const siteUrl = (process.env.SITE_URL ?? process.env.NEXT_PUBLIC_SITE_URL ?? "https://example.com")
   .replace(/\/+$/u, "");
 const publicBaseUrl = basePath && !siteUrl.endsWith(basePath)
@@ -66,6 +77,7 @@ const siteAddress = configuredSiteAddress(siteConfig, process.env);
 const sameSite = sameSiteMatcher(siteAddress, basePath);
 const siteName = process.env.SITE_NAME ?? siteConfig.name;
 const siteDescription = process.env.SITE_DESCRIPTION ?? siteConfig.description;
+const siteLang = /^en/iu.test(String(siteConfig.locale ?? "")) ? "en" : "zh";
 
 const fail = (sourcePath, message) => {
   throw new Error(`${sourcePath}: ${message}`);
@@ -296,11 +308,12 @@ function resolveFileEntry(file, markdownPath, sourcePath, options = {}) {
   const assetOptions = options.assetOptions ?? {};
   const src = file.src;
   const name = fileName(src);
+  const lang = options.lang ?? siteLang;
   const entry = {
     name,
     title: file.title || name,
     ...(file.note ? { note: file.note } : {}),
-    format: formatLabel(src),
+    format: formatLabel(src, lang),
     icon: fileIcon(src),
   };
   if (isRemoteSrc(src)) {
@@ -324,9 +337,9 @@ function resolveFileEntry(file, markdownPath, sourcePath, options = {}) {
     // Rendered now into its own file next to the copy; the page only links to it and the
     // preview fetches it on demand. Images next to the Markdown file are copied too.
     const { content } = matter(fs.readFileSync(resolved.path, "utf8"));
-    const html = renderFilePreview(rewriteMarkdownAssets(content.trim(), resolved.path, sourcePath, assetOptions));
+    const html = renderFilePreview(rewriteMarkdownAssets(content.trim(), resolved.path, sourcePath, assetOptions), { lang });
     const { destination } = assetFiles.get(url.split(/[?#]/u, 1)[0]);
-    fs.writeFileSync(previewFileName(destination), previewDocument(html, { title: entry.title }));
+    fs.writeFileSync(previewFileName(destination), previewDocument(html, { title: entry.title, lang, icon: previewIcon() }));
     next.previewSrc = previewFileName(url.split(/[?#]/u, 1)[0]);
   }
   return next;
@@ -351,6 +364,9 @@ function rewriteFileFences(content, markdownPath, sourcePath, options = {}) {
       layout: read.layout,
       ...(read.title ? { title: read.title } : {}),
       files: read.files.map((file) => resolveFileEntry(file, markdownPath, sourcePath, options)),
+      // The YAML as written, so a page that shows its own source (the
+      // component reference) shows what the author typed, not this data.
+      source: fence.body.replace(/\n$/u, ""),
     };
     const indent = " ".repeat(fence.indent);
     lines.splice(
@@ -505,6 +521,7 @@ function validateAndNormalize(data, content, markdownPath, kind, sourcePath, lin
       ),
       markdownPath,
       sourcePath,
+      { lang: siteLang },
     ),
   };
 }
@@ -619,7 +636,7 @@ function readColumnReferences(posts) {
         column: slug,
         columnTitle: title,
         columnDescription: description,
-        columnStatus: optionalString(value, "status", sourcePath) ?? "持续更新",
+        columnStatus: columnStatusOf(optionalString(value, "status", sourcePath)),
         columnCover: optionalString(value, "cover", sourcePath),
         columnCoverAlt: optionalString(value, "coverAlt", sourcePath),
         order: order + 1,
@@ -674,6 +691,8 @@ function readHandbookDocs() {
         );
       }
 
+      const docLang = docPath === "en" || docPath.startsWith("en/") ? "en" : "zh";
+      if (siteLang === "en" && docLang === "zh") return [];
       const content = rewriteFileFences(
         rewriteMarkdownAssets(
           rewriteUiFences(parsed.content.trim(), fullPath, sourcePath, frontMatterLines + leadingLines(parsed.content), assetOptions),
@@ -683,7 +702,7 @@ function readHandbookDocs() {
         ),
         fullPath,
         sourcePath,
-        fileOptions,
+        { ...fileOptions, lang: docLang },
       );
 
       return [{
@@ -724,8 +743,8 @@ const allHandbookDocs = readHandbookDocs().map((doc) =>
     ? { ...doc, lang: "en", path: doc.path === "en" ? "index" : doc.path.slice(3) }
     : { ...doc, lang: "zh" },
 );
-const zhHandbookDocs = allHandbookDocs.filter((doc) => doc.lang === "zh");
 const enHandbookDocs = allHandbookDocs.filter((doc) => doc.lang === "en");
+const zhHandbookDocs = siteLang === "en" ? enHandbookDocs : allHandbookDocs.filter((doc) => doc.lang === "zh");
 const gardenIndexDoc = zhHandbookDocs.find((doc) => doc.path === "index") ?? null;
 const gardenDocs = zhHandbookDocs.filter((doc) => doc.path !== "index");
 const gardenIndexDocEn = enHandbookDocs.find((doc) => doc.path === "index") ?? null;
@@ -899,7 +918,7 @@ export const siteLinks = ${JSON.stringify({ address: siteAddress, basePath, trai
 `,
 );
 fs.mkdirSync(path.join(root, "public"), { recursive: true });
-fs.writeFileSync(path.join(root, "public", "search-index.json"), JSON.stringify(buildSearchIndex({ posts, columns, thoughts })));
+fs.writeFileSync(path.join(root, "public", "search-index.json"), JSON.stringify(buildSearchIndex({ posts, columns, thoughts }, { lang: siteLang })));
 for (const name of fs.readdirSync(path.join(root, "public"))) {
   if (/^search-full\.[0-9a-f]+\.json$/u.test(name) && name !== fullIndex.fileName) fs.rmSync(path.join(root, "public", name));
 }
@@ -952,7 +971,7 @@ function writeRssFeed(fileName, entries) {
     <link>${escapeXml(publicBaseUrl)}</link>
     <atom:link href="${escapeXml(`${publicBaseUrl}/${fileName}`)}" rel="self" type="application/rss+xml" />
     <description>${escapeXml(siteDescription)}</description>
-    <language>zh-CN</language>
+    <language>${siteLang === "en" ? "en-US" : "zh-CN"}</language>
     <lastBuildDate>${feedLastBuildDate(entries)}</lastBuildDate>${rssItems}
   </channel>
 </rss>
@@ -965,14 +984,16 @@ writeRssFeed(
   posts.map((entry) => feedEntry(entry, `/blog/${entry.path}/`)),
 );
 const sitemapEntries = [
-  "/", "/blog/", "/thoughts/", "/columns/", "/about/", "/garden/",
-  ...gardenDocs.map((entry) => `/garden/${entry.path}/`),
-  ...(gardenIndexDocEn ? ["/garden/en/"] : []),
-  ...gardenDocsEn.map((entry) => `/garden/en/${entry.path}/`),
-  ...posts.map((entry) => `/blog/${entry.path}/`),
-  ...columns.map((entry) => `/columns/${entry.column}/${columnEntryPath(entry)}/`),
-  ...thoughts.map((entry) => `/thoughts/${entry.slug}/`),
-].map(pageAddress);
+  ...new Set([
+    "/", "/blog/", "/thoughts/", "/columns/", "/about/", "/garden/",
+    ...gardenDocs.map((entry) => `/garden/${entry.path}/`),
+    ...(gardenIndexDocEn ? ["/garden/en/"] : []),
+    ...gardenDocsEn.map((entry) => `/garden/en/${entry.path}/`),
+    ...posts.map((entry) => `/blog/${entry.path}/`),
+    ...columns.map((entry) => `/columns/${entry.column}/${columnEntryPath(entry)}/`),
+    ...thoughts.map((entry) => `/thoughts/${entry.slug}/`),
+  ].map(pageAddress)),
+];
 // Card URLs in published entries: the only pages the link-card Worker may read.
 fs.writeFileSync(
   path.join(publicRoot, "link-allowlist.json"),

package/scripts/favicon-ico.mjs

@@ -14,6 +14,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { resolveBrand } from "./brand.mjs";
+import { siteCliLang } from "../ui/core/cli-locale.mjs";
 
 export const ICO_SIZES = [16, 32, 48];
 
@@ -80,9 +81,10 @@ export async function writeFaviconIco({ source, outDir, siteRoot }) {
 
 export async function runFaviconStep({ siteRoot, env = process.env, out = process.stdout }) {
   const outDir = path.join(siteRoot, "dist", "client");
-  const warn = (line) => out.write(`警告：${line}\n`);
+  const en = siteCliLang(siteRoot) === "en";
+  const warn = (line) => out.write(en ? `Warning: ${line}\n` : `警告：${line}\n`);
   if (!fs.existsSync(outDir)) {
-    warn(`找不到构建产物 ${path.relative(siteRoot, outDir)}，没有生成 favicon.ico。`);
+    warn(en ? `No build output at ${path.relative(siteRoot, outDir)}; favicon.ico was not generated.` : `找不到构建产物 ${path.relative(siteRoot, outDir)}，没有生成 favicon.ico。`);
     return 0;
   }
   const configFile = path.join(siteRoot, "site.config.yaml");
@@ -91,19 +93,20 @@ export async function runFaviconStep({ siteRoot, env = process.env, out = proces
   const { favicon } = resolveBrand(siteRoot, config, basePath);
   const source = faviconSource(siteRoot, outDir, favicon, basePath);
   if (source === null) {
-    warn(`brand.favicon 是外部地址 ${favicon}，没有生成 favicon.ico。`);
+    warn(en ? `brand.favicon is an external URL (${favicon}); favicon.ico was not generated.` : `brand.favicon 是外部地址 ${favicon}，没有生成 favicon.ico。`);
     return 0;
   }
   if (!source) {
-    warn(`找不到图标文件 ${favicon}，没有生成 favicon.ico。`);
+    warn(en ? `Icon file ${favicon} not found; favicon.ico was not generated.` : `找不到图标文件 ${favicon}，没有生成 favicon.ico。`);
     return 0;
   }
   try {
     const result = await writeFaviconIco({ source, outDir, siteRoot });
-    if (result.status === "kept") out.write("favicon.ico：使用 public/favicon.ico。\n");
+    if (result.status === "kept") out.write(en ? "favicon.ico: using public/favicon.ico.\n" : "favicon.ico：使用 public/favicon.ico。\n");
+    else if (en) out.write(`favicon.ico: generated from ${path.relative(siteRoot, source)}${result.sizes ? ` (${result.sizes.join(", ")} px)` : ""}.\n`);
     else out.write(`favicon.ico：由 ${path.relative(siteRoot, source)} 生成${result.sizes ? `（${result.sizes.join("、")} px）` : ""}。\n`);
   } catch (error) {
-    warn(`favicon.ico 生成失败（${error.message}），页面仍使用 ${favicon}。`);
+    warn(en ? `favicon.ico generation failed (${error.message}); pages still use ${favicon}.` : `favicon.ico 生成失败（${error.message}），页面仍使用 ${favicon}。`);
   }
   return 0;
 }

package/scripts/file-preview.mjs

@@ -68,14 +68,15 @@ export function rehypePreviewSafety() {
  * their language, outside links carry .ext. (Copy buttons, link cards and
  * favicons are article-only.)
  */
-export function rehypePreviewShape() {
+export function rehypePreviewShape({ lang = "zh" } = {}) {
+  const tableAriaLabel = lang === "en" ? "Scrollable table" : "表格，可横向滚动";
   return (tree) => {
     visit(tree, "element", (node, index, parent) => {
       if (node.tagName === "table" && !(parent?.type === "element" && parent.properties?.className?.includes?.("table-wrap"))) {
         parent.children[index] = {
           type: "element",
           tagName: "div",
-          properties: { className: ["table-wrap"], role: "region", ariaLabel: "表格，可横向滚动", tabIndex: 0 },
+          properties: { className: ["table-wrap"], role: "region", ariaLabel: tableAriaLabel, tabIndex: 0 },
           children: [node],
         };
         return "skip";
@@ -95,7 +96,7 @@ export function rehypePreviewShape() {
 }
 
 /** Markdown → the preview's HTML. `idPrefix` keeps heading ids apart from the article's own. */
-export function renderFilePreview(markdown, { idPrefix = "gf-" } = {}) {
+export function renderFilePreview(markdown, { idPrefix = "gf-", lang = "zh" } = {}) {
   return String(
     unified()
       .use(remarkParse)
@@ -106,7 +107,7 @@ export function renderFilePreview(markdown, { idPrefix = "gf-" } = {}) {
       .use(rehypeSlug, { prefix: idPrefix })
       .use(rehypeHighlight)
       .use(rehypePreviewSafety)
-      .use(rehypePreviewShape)
+      .use(rehypePreviewShape, { lang })
       .use(rehypeStringify)
       .processSync(markdown),
   );
@@ -201,14 +202,16 @@ export function previewStyleSheet() {
  * JavaScript who follows the 预览 link gets something readable. The drawer
  * takes only what is inside <main>.
  */
-export function previewDocument(html, { title = "预览" } = {}) {
+export function previewDocument(html, { title = "", lang = "zh", icon = "" } = {}) {
+  const docTitle = title || (lang === "en" ? "Preview" : "预览");
+  const htmlLang = lang === "en" ? "en" : "zh-CN";
   return `<!doctype html>
-<html lang="zh-CN">
+<html lang="${htmlLang}">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex">
-<title>${escapeText(title)}</title>
+<title>${escapeText(docTitle)}</title>${icon ? `\n<link rel="icon" href="${escapeText(icon).replace(/"/gu, "&quot;")}"${/\.svg(?:[?#]|$)/iu.test(icon) ? ' type="image/svg+xml"' : ""}>` : ""}
 <style>${previewStyleSheet()}</style>
 </head>
 <body><main class="gf-preview-doc">

package/scripts/handbook-allowlist.mjs

@@ -66,3 +66,21 @@ export const ALLOWED_NON_ENV_UPPER_SNAKE = {
   KB: "Kilobyte unit",
   GB: "Gigabyte unit",
 };
+
+/**
+ * Explicit allowlist of CJK characters permitted on English handbook pages:
+ * - "中": the "中 / EN" language switcher in the header
+ * - "丨" / "｜": the two-line title split delimiter character where explained in prose
+ * - figureAllKeyword: the literal config value `"全部"` ONLY in
+ *   docs/handbook/en/components/figure.md on the `parts[].id` field row
+ */
+export const ALLOWED_EN_HANDBOOK_CJK = {
+  switcher: "中",
+  titleSplitChars: new Set(["丨", "｜"]),
+  figureAllKeyword: {
+    file: "docs/handbook/en/components/figure.md",
+    routePattern: /(?:^|\/)garden\/en\/components\/figure(?:\/index\.html|\/)?$/u,
+    linePattern: /^\|\s*`parts\[\]\.id`\s*\|/u,
+    literal: '"全部"',
+  },
+};

package/scripts/handbook-facts.mjs

@@ -12,6 +12,7 @@ import { pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { CATALOG } from "../ui/garden/catalog.mjs";
 import {
+  ALLOWED_EN_HANDBOOK_CJK,
   ALLOWED_EXTERNAL_FLAGS,
   ALLOWED_NON_ENV_UPPER_SNAKE,
 } from "./handbook-allowlist.mjs";
@@ -154,7 +155,7 @@ function deriveMakefileFacts(root = ROOT) {
   const targets = new Set();
   const variables = new Set(["MAKE"]);
 
-  for (const rel of ["templates/site/Makefile", "Makefile"]) {
+  for (const rel of ["templates/site/Makefile", "templates/site/Makefile.en", "Makefile"]) {
     const file = path.join(root, rel);
     if (!fs.existsSync(file)) continue;
     const text = fs.readFileSync(file, "utf8");
@@ -217,19 +218,21 @@ function deriveEnvVars(root = ROOT) {
     }
   }
 
-  // .env.example
-  const envExample = path.join(root, ".env.example");
-  if (fs.existsSync(envExample)) {
-    const text = fs.readFileSync(envExample, "utf8");
-    for (const match of text.matchAll(/^#?\s*([A-Z][A-Z0-9_]+)=/gmu)) {
-      envVars.add(match[1]);
+  // .env.example & .env.en.example
+  for (const envRel of [".env.example", ".env.en.example"]) {
+    const envExample = path.join(root, envRel);
+    if (fs.existsSync(envExample)) {
+      const text = fs.readFileSync(envExample, "utf8");
+      for (const match of text.matchAll(/^#?\s*([A-Z][A-Z0-9_]+)=/gmu)) {
+        envVars.add(match[1]);
+      }
     }
   }
 
   // GitHub workflows and template Makefiles
   const workflowFiles = [
     ...walkFiles(path.join(root, ".github/workflows"), (f) => /\.ya?ml$/u.test(f)),
-    ...walkFiles(path.join(root, "templates"), (f) => /\.ya?ml$|Makefile$/u.test(f)),
+    ...walkFiles(path.join(root, "templates"), (f) => /\.ya?ml$|Makefile(?:\.en)?$/u.test(f)),
   ];
   for (const file of workflowFiles) {
     const text = fs.readFileSync(file, "utf8");
@@ -272,7 +275,7 @@ function deriveSiteConfigKeys(root = ROOT) {
     }
   }
 
-  for (const rel of ["templates/site/site.config.yaml", "site.config.yaml"]) {
+  for (const rel of ["templates/site/site.config.yaml", "templates/site/site.config.en.yaml", "site.config.yaml"]) {
     const file = path.join(root, rel);
     if (!fs.existsSync(file)) continue;
     const text = fs.readFileSync(file, "utf8");
@@ -357,7 +360,7 @@ function deriveCheckCodes(root = ROOT) {
   // ui/core/validate.mjs & ui/core/parse.mjs
   for (const rel of ["ui/core/validate.mjs", "ui/core/parse.mjs"]) {
     const text = fs.readFileSync(path.join(root, rel), "utf8");
-    for (const match of text.matchAll(/\b(?:add|report)\(\s*["']([a-z0-9-]+)["']\s*,\s*[^,]+,\s*[^,)]+(?:,\s*["'](error|warning)["'])?\s*\)/gu)) {
+    for (const match of text.matchAll(/\b(?:add|report)\(\s*["']([a-z0-9-]+)["']\s*,\s*(?:[^,()]|\([^()]*\))+,\s*(?:[^,()]|\([^()]*\))+(?:,\s*["'](error|warning)["'])?\s*\)/gu)) {
       record(match[1], match[2] === "warning" ? "warning" : "error");
     }
   }
@@ -1088,6 +1091,294 @@ export function checkHandbookPairs(root = ROOT) {
   return issues;
 }
 
+const CJK_RE = /[\u3000-\u303f\u3400-\u9fff\uf900-\ufaff\uff00-\uffef]/gu;
+
+function findDisallowedEnCjk(line, { allowTitleSplit = false } = {}) {
+  const disallowed = [];
+  for (const match of line.matchAll(CJK_RE)) {
+    const ch = match[0];
+    if (allowTitleSplit && ALLOWED_EN_HANDBOOK_CJK.titleSplitChars.has(ch)) continue;
+    disallowed.push(ch);
+  }
+  return disallowed;
+}
+
+/**
+ * Extract local relative file paths included or embedded by an English handbook Markdown page
+ * (Markdown images, HTML media tags, and `garden file` / `garden figure` / `garden html` fences).
+ */
+function extractIncludedHandbookFiles(markdown, mdFile, root = ROOT) {
+  const handbookRoot = path.join(root, "docs/handbook");
+  const baseDir = path.dirname(mdFile);
+  const included = new Set();
+
+  const addIfLocal = (rawRef) => {
+    if (!rawRef || typeof rawRef !== "string") return;
+    const cleaned = rawRef.trim().replace(/^<|>$/gu, "").split(/[?#]/u, 1)[0];
+    if (!cleaned || /^(?:[a-z]+:)?\/\//iu.test(cleaned) || cleaned.startsWith("/") || cleaned.startsWith("#") || cleaned.startsWith("data:")) {
+      return;
+    }
+    const resolved = path.resolve(baseDir, decodeURIComponent(cleaned));
+    const relToHandbook = path.relative(handbookRoot, resolved);
+    if (!relToHandbook.startsWith("..") && !path.isAbsolute(relToHandbook) && fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+      included.add(resolved);
+    }
+  };
+
+  for (const match of markdown.matchAll(/!\[[^\]]*\]\(([^)]+)\)/gu)) {
+    addIfLocal(match[1].trim().split(/\s+/u, 1)[0]);
+  }
+  for (const match of markdown.matchAll(/<(?:img|audio|video|source)\b[^>]*\bsrc=["']([^"']+)["']/giu)) {
+    addIfLocal(match[1]);
+  }
+  const { fences } = parseMarkdownRegions(markdown);
+  for (const fence of fences) {
+    if (!fence.info.startsWith("garden ")) continue;
+    const bodyText = fence.bodyLines.map((l) => l.text).join("\n");
+    for (const srcMatch of bodyText.matchAll(/^\s*(?:-\s*)?(?:src|image)\s*:\s*(.+)$/gmu)) {
+      addIfLocal(srcMatch[1].replace(/^(["'])(.*)\1$/u, "$2"));
+    }
+  }
+  return [...included];
+}
+
+/**
+ * Strip the narrow, line-specific `"全部"` config value exception when checking
+ * `docs/handbook/en/components/figure.md` on the `parts[].id` field row.
+ */
+function stripAllowedFigureAllKeywordInLine(relFile, line) {
+  const rule = ALLOWED_EN_HANDBOOK_CJK.figureAllKeyword;
+  if (relFile === rule.file && rule.linePattern.test(line)) {
+    return line.replaceAll(`\`${rule.literal}\``, "").replaceAll(rule.literal, "");
+  }
+  return line;
+}
+
+/**
+ * Strip the narrow, row-specific `<code>"全部"</code>` config value exception when
+ * checking built HTML for `/garden/en/components/figure` on the `parts[].id` table row.
+ */
+export function stripAllowedFigureAllKeywordInHtml(html, pageLabel = "") {
+  const rule = ALLOWED_EN_HANDBOOK_CJK.figureAllKeyword;
+  if (!rule.routePattern.test(String(pageLabel))) return String(html);
+  return String(html).replace(/<tr\b[^>]*>[\s\S]*?<\/tr>/giu, (tr) => {
+    if (!/<code>parts\[\]\.id<\/code>/u.test(tr)) return tr;
+    return tr.replace(/<code>(?:"|&quot;)全部(?:"|&quot;)<\/code>/gu, '<code>"all"</code>');
+  });
+}
+
+/**
+ * Every English handbook page under docs/handbook/en/ (including fenced code blocks and
+ * any included/embedded files) must not contain CJK characters, except the explicit allowlist.
+ * Note: This static check inspects Markdown source, embedded assets, and pre-rendered HTML files;
+ * it does not cover client-side runtime rendering or hydration (which is verified by browser tests).
+ */
+export function checkEnglishHandbookNoCjk(root = ROOT) {
+  const enRoot = path.join(root, "docs/handbook/en");
+  if (!fs.existsSync(enRoot)) return [];
+  const issues = [];
+  const checkedAssets = new Set();
+
+  const checkFileLines = (filePath, allowTitleSplit = false) => {
+    const relFile = path.relative(root, filePath).replace(/\\/g, "/");
+    const lines = fs.readFileSync(filePath, "utf8").split(/\r?\n/u);
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      const lineAllowSplit = allowTitleSplit && /(?:title|split|delimiter|heading|two-line|` \| `)/iu.test(line);
+      const scannedLine = stripAllowedFigureAllKeywordInLine(relFile, line);
+      const bad = findDisallowedEnCjk(scannedLine, { allowTitleSplit: lineAllowSplit });
+      if (bad.length > 0) {
+        const sample = [...new Set(bad)].slice(0, 8).join("");
+        issues.push({
+          file: relFile,
+          line: i + 1,
+          kind: "en-cjk",
+          message: `English handbook contains CJK character(s) "${sample}": ${line.trim().slice(0, 80)}`,
+        });
+      }
+    }
+  };
+
+  const enFiles = walkFiles(enRoot);
+  for (const file of enFiles) {
+    checkedAssets.add(file);
+    checkFileLines(file, file.endsWith(".md"));
+    if (file.endsWith(".md")) {
+      const content = fs.readFileSync(file, "utf8");
+      for (const asset of extractIncludedHandbookFiles(content, file, root)) {
+        if (checkedAssets.has(asset)) continue;
+        checkedAssets.add(asset);
+        if (/\.(?:md|markdown|svg|html|htm|txt|csv|tsv|json|ya?ml)$/iu.test(asset)) {
+          checkFileLines(asset, false);
+        }
+      }
+    }
+  }
+
+  const builtPreviewDir = path.join(root, "public/media/garden-docs/en");
+  for (const file of walkFiles(builtPreviewDir)) {
+    if (checkedAssets.has(file)) continue;
+    checkedAssets.add(file);
+    if (/\.(?:md|markdown|svg|html|htm|txt|csv|tsv|json|ya?ml)$/iu.test(file)) {
+      checkFileLines(file, false);
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Inspect a single built HTML document for an English handbook route (or the
+ * English 404 output), covering <head> meta tags, <title>, visible text, and
+ * user-facing attributes (`content`, `alt`, `title`, `aria-label`, `placeholder`).
+ * Only the `中` language switcher, the `丨` / `｜` title-split delimiter explanation,
+ * and the narrow `"全部"` config value on `/garden/en/components/figure` (`parts[].id` row)
+ * are permitted.
+ * Note: This check inspects static HTML markup only and does not cover runtime rendering
+ * or client-side hydration in a real browser.
+ */
+export function findBuiltEnglishHtmlCjk(html, pageLabel = "/garden/en") {
+  const issues = [];
+  const cleaned = stripAllowedFigureAllKeywordInHtml(
+    String(html)
+      .replace(/<script[\s\S]*?<\/script>/giu, "")
+      .replace(/<style[\s\S]*?<\/style>/giu, ""),
+    pageLabel,
+  );
+
+  const recordIfCjk = (value, context, allowTitleSplit = false) => {
+    const text = String(value ?? "").trim();
+    if (!text) return;
+    if (text === ALLOWED_EN_HANDBOOK_CJK.switcher) return;
+    const bad = findDisallowedEnCjk(text, { allowTitleSplit });
+    if (bad.length > 0) {
+      const sample = [...new Set(bad)].slice(0, 8).join("");
+      issues.push({
+        file: pageLabel,
+        line: 1,
+        kind: "en-built-cjk",
+        message: `Built English HTML (${context}) contains CJK character(s) "${sample}": ${text.slice(0, 100)}`,
+      });
+    }
+  };
+
+  // 1. Check <head> <title> and <meta> tags
+  const headMatch = /<head\b[^>]*>([\s\S]*?)<\/head>/iu.exec(cleaned);
+  const headHtml = headMatch ? headMatch[1] : "";
+  for (const m of headHtml.matchAll(/<title\b[^>]*>([\s\S]*?)<\/title>/giu)) {
+    recordIfCjk(m[1], "<title>", false);
+  }
+  for (const m of headHtml.matchAll(/<meta\b[^>]*>/giu)) {
+    const tag = m[0];
+    const nameOrProp =
+      /\b(?:name|property)=["']([^"']*)["']/iu.exec(tag)?.[1] ?? "<meta>";
+    const content = /\bcontent=["']([^"']*)["']/iu.exec(tag)?.[1] ?? "";
+    recordIfCjk(content, `meta[${nameOrProp}]`, false);
+  }
+
+  // 2. Check user-facing attributes across the entire document
+  for (const m of cleaned.matchAll(/\s(aria-label|title|placeholder|alt)=["']([^"']*)["']/giu)) {
+    recordIfCjk(m[2], `attr[${m[1]}]`, false);
+  }
+
+  // 3. Check all text nodes across the entire document
+  for (const m of cleaned.matchAll(/>([^<]+)</gu)) {
+    const text = m[1].trim();
+    if (!text) continue;
+    recordIfCjk(text, "text", true);
+  }
+
+  return issues;
+}
+
+/**
+ * Check any static-export HTML files already present under dist/client/garden/en/.
+ * Note: Static CJK checks do not cover runtime rendering or hydration of routes such as
+ * the shared root 404.html; runtime rendering is verified separately in a real browser.
+ */
+export function checkBuiltEnglishHandbookHtmlFiles(root = ROOT) {
+  const clientDir = path.join(root, "dist/client");
+  const clientEnDir = path.join(clientDir, "garden/en");
+  const issues = [];
+  if (fs.existsSync(clientEnDir)) {
+    for (const file of walkFiles(clientEnDir, (f) => f.endsWith(".html"))) {
+      const rel = path.relative(root, file).replace(/\\/g, "/");
+      const html = fs.readFileSync(file, "utf8");
+      issues.push(...findBuiltEnglishHtmlCjk(html, rel));
+    }
+  }
+  return issues;
+}
+
+const HANDBOOK_EMBEDDED_TEMPLATES = [
+  {
+    handbookFile: "docs/handbook/config.md",
+    templateFile: "templates/site/site.config.yaml",
+    label: "site.config.yaml",
+  },
+  {
+    handbookFile: "docs/handbook/en/config.md",
+    templateFile: "templates/site/site.config.en.yaml",
+    label: "site.config.en.yaml",
+  },
+  {
+    handbookFile: "docs/handbook/deploy.md",
+    templateFile: "templates/workflows/pages.yml",
+    label: "pages.yml",
+  },
+  {
+    handbookFile: "docs/handbook/en/deploy.md",
+    templateFile: "templates/workflows/pages.en.yml",
+    label: "pages.en.yml",
+  },
+];
+
+/**
+ * Verify that the Chinese and English handbook config/deploy pages embed their
+ * corresponding site.config.yaml and pages.yml templates verbatim.
+ */
+export function checkHandbookTemplates(root = ROOT) {
+  const issues = [];
+  for (const { handbookFile, templateFile, label } of HANDBOOK_EMBEDDED_TEMPLATES) {
+    const fullHandbook = path.join(root, handbookFile);
+    const fullTemplate = path.join(root, templateFile);
+    if (!fs.existsSync(fullHandbook) || !fs.existsSync(fullTemplate)) continue;
+    const expected = fs.readFileSync(fullTemplate, "utf8").replace(/\r\n/gu, "\n").trimEnd();
+    const { fences } = parseMarkdownRegions(fs.readFileSync(fullHandbook, "utf8"));
+    const yamlFence = fences.find((f) => f.lang === "yaml" || f.lang === "yml");
+    if (!yamlFence) {
+      issues.push({
+        file: handbookFile,
+        line: 1,
+        kind: "template-drift",
+        message: `Missing YAML fence for template ${templateFile} (${label})`,
+      });
+      continue;
+    }
+    const actual = yamlFence.bodyLines.map((l) => l.text).join("\n").replace(/\r\n/gu, "\n").trimEnd();
+    if (actual !== expected) {
+      const actualLines = actual.split("\n");
+      const expectedLines = expected.split("\n");
+      let diffIdx = 0;
+      while (
+        diffIdx < actualLines.length &&
+        diffIdx < expectedLines.length &&
+        actualLines[diffIdx] === expectedLines[diffIdx]
+      ) {
+        diffIdx += 1;
+      }
+      const line = yamlFence.bodyLines[diffIdx]?.lineNumber ?? yamlFence.startLine;
+      issues.push({
+        file: handbookFile,
+        line,
+        kind: "template-drift",
+        message: `Embedded ${label} fence does not match ${templateFile} verbatim (first difference at template line ${diffIdx + 1})`,
+      });
+    }
+  }
+  return issues;
+}
+
 /**
  * Scan all docs/handbook/ and app/garden/ files and return any fact-check failures.
  */
@@ -1103,6 +1394,9 @@ export function checkAllHandbookFacts(root = ROOT) {
     issues.push(...checkFileFacts(file, content, facts, root));
   }
   issues.push(...checkHandbookPairs(root));
+  issues.push(...checkHandbookTemplates(root));
+  issues.push(...checkEnglishHandbookNoCjk(root));
+  issues.push(...checkBuiltEnglishHandbookHtmlFiles(root));
   const svgFiles = walkFiles(path.join(root, "docs/handbook"), (f) => f.endsWith(".svg"));
   for (const svgFile of svgFiles) {
     const svgContent = fs.readFileSync(svgFile, "utf8");
@@ -1133,6 +1427,6 @@ if (invokedDirectly) {
     }
     process.exitCode = 1;
   } else {
-    console.log("Handbook fact-check passed: 0 issues.");
+    console.log("Handbook fact-check passed: 0 issues (static source/HTML check; does not cover runtime rendering).");
   }
 }