hd-garden 0.6.0 → 0.7.0

package/docs/handbook/writing.md

@@ -0,0 +1,148 @@
+---
+title: 写文章与随想
+navTitle: 写文章与随想
+description: 长文与随想的 Front Matter 字段、代码块对比、提示框、外链卡片、公式与流程图写法。
+section: writing-and-reading
+order: 10
+---
+
+Garden 的内容分为两类：**长文**（放在 `content/posts/`）和**随想**（放在 `content/thoughts/`）。两者都使用 UTF-8 编码的 Markdown 文件，文件名只能包含小写字母、数字和连字符（`a-z`、`0-9`、`-`）。
+
+## 1. 长文 Front Matter（`content/posts/*.md`）
+
+用 `make new DIR=systems SLUG=wal-checkpoint TITLE="深入理解 WAL丨检查点与恢复流程"` 创建文章，或者手动新建 `.md` 文件：
+
+```yaml
+---
+title: 深入理解 WAL丨检查点与恢复流程
+date: 2026-10-18
+updated: 2026-10-19
+description: 拆解预写日志在并发读写下的页面可见性规则，以及后台检查点如何控制日志文件体积。
+tags:
+  - 数据库
+  - 存储
+pinned: false
+draft: false
+cover: windowsill-herbs.svg
+original: https://example.com/original-post
+references:
+  - title: SQLite Write-Ahead Logging
+    url: https://www.sqlite.org/wal.html
+  - title: 《Database Internals》
+---
+```
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `title` | 是 | 字符串 | 文章标题。中间写 `丨`、`｜` 或 ` \| ` 会分成两行并按字数缩放字号 |
+| `date` | 是 | 日期字符串 | 发布日期（如 `2026-10-18` 或带时区的 ISO 时间） |
+| `description` | 是 | 字符串 | 文章摘要，显示在正文开头导语、列表页与搜索引擎摘要中 |
+| `updated` | 否 | 日期字符串 | 最后更新日期，显示在文章元信息栏并用于 RSS 排序 |
+| `publishAt` | 否 | 日期字符串 | 定时发布时间；早于当前构建时间（或设置 `CONTENT_INCLUDE_DRAFTS=1`）才会发布 |
+| `tags` | 否 | 字符串数组 | 文章标签列表，点击标签会跳转到 `/blog?t=<标签>` 筛选 |
+| `pinned` | 否 | 布尔值 | 设为 `true` 时显示在站点首页「置顶」区域 |
+| `draft` | 否 | 布尔值 | 设为 `true` 时视为草稿，正式构建会自动跳过 |
+| `cover` | 否 | 路径字符串 | 封面图路径，相对 `content/covers/` 目录 |
+| `original` | 否 | 完整链接 | 原文链接，设置后在标题下方元信息栏显示 `原文 ↗` |
+| `references` | 否 | `{ title, url? }[]` | 文末参考资料列表，构建期自动提取域名并渲染在正文底部的「参考」卡片中 |
+
+> [!CAUTION]
+> 不要在 Front Matter 里手写 `slug` 字段（`npx garden check` 会报 `unexpected-slug` 错误：`不要写 slug，文件名就是标识`）。文章也没有 `topic` 分类字段。
+
+## 2. 代码块与「代码 / 对比上一版」切换
+
+普通代码块在右上角带有语言名称（如 `RUST`、`TS`、`PYTHON`、`SHELL`）和复制按钮。
+
+如果你想展示某段代码修改前后的对比，**先放一段完整代码块，紧接着放一段 `diff` 代码块**。渲染器会自动把它们合并成一个带 **「代码」** 和 **「对比上一版」** 两个切换按钮的代码框：
+
+````markdown
+```go
+func openStore(path string) (*Store, error) {
+	return openWithMode(path, ModeWAL)
+}
+```
+
+```diff
+ func openStore(path string) (*Store, error) {
+-	return openWithMode(path, ModeJournal)
++	return openWithMode(path, ModeWAL)
+ }
+```
+````
+
+实际渲染效果如下（点击右上角的 **「代码」** 与 **「对比上一版」** 可以切换，点击复制按钮始终复制前面的完整代码）：
+
+```go
+func openStore(path string) (*Store, error) {
+	return openWithMode(path, ModeWAL)
+}
+```
+
+```diff
+ func openStore(path string) (*Store, error) {
+-	return openWithMode(path, ModeJournal)
++	return openWithMode(path, ModeWAL)
+ }
+```
+
+> [!IMPORTANT]
+> `diff` 代码块前面必须紧挨着一段完整代码块（中间只能隔空行）；如果单独放一段 `diff` 而前面没有完整代码块，`npx garden check` 会报 `diff-orphan` 错误。
+
+## 3. 中文加粗、荧光笔高亮与提示框
+
+- **中文标点旁加粗**：内置 `remark-cjk-friendly`，紧挨中文括号、引号或顿号写 `**像「这样」的加粗**` 能正常解析，不需要在星号两侧加空格。
+- **荧光笔高亮**：用 `<u>重点句子</u>` 或 `<mark>重点句子</mark>` 可以给文字加上暖黄色荧光笔底纹，效果如：<u>这一句带有荧光笔下划线底色</u>。
+- **提示框（Callouts）**：支持 `> [!NOTE]`、`> [!TIP]`、`> [!IMPORTANT]`、`> [!WARNING]`、`> [!CAUTION]`（以及 `INFO`、`SUCCESS`、`DANGER`、`FAILURE`）。在标记同行末尾写文字可替换默认标题：
+
+```markdown
+> [!WARNING] 升级前先备份数据目录
+> 修改页大小后需要重建索引文件，不能直接原地回退。
+```
+
+> [!WARNING] 升级前先备份数据目录
+> 修改页大小后需要重建索引文件，不能直接原地回退。
+
+## 4. 本地图片与外部链接卡片
+
+- **本地图片与随文目录**：如果文章路径是 `content/posts/my-post.md`，把配图放在同名的 `content/posts/my-post/` 文件夹下，在文中以 `./my-post/diagram.svg` 相对路径引用。构建时会自动复制图片、读取像素宽高，并把 `alt` 文字（以 `image`、`截图`、`img` 开头的默认占位词除外）渲染成图注 `<figcaption>`。
+- **行内外部链接**：正文里的外部链接会自动加上目标站点的 Favicon 小图标，并保证图标与链接第一个字同行不折断。
+- **链接卡片**：有两种写法可以把外部链接渲染成带网站名、标题和简介的链接卡片：
+  1. 把完整网址单独写成一行段落（前后空行）：`https://spec.commonmark.org/`
+  2. 在段落内的链接末尾紧跟 `{card}`（中间不加空格）：`参见 [CommonMark 规范](https://spec.commonmark.org/){card}。`
+  也可以运行 `make embed URL="https://example.com"` 抓取目标网页的 Open Graph 标题、摘要和封面图。
+
+## 5. 数学公式与 Mermaid 图表
+
+- **LaTeX 数学公式**：使用 KaTeX 在构建与渲染期直接排版。行内公式写 `$L = \lambda W$`，独立公式块写 `$$...$$`。公式里带下划线的多字母变量名（如 `group_num`、`max_batch`）会自动保护为正体标识符 `\mathrm{group\_num}`，而 `W_q`、`H_{kv}` 等单字母带下标仍保持标准数学下标。
+- **Mermaid 图表**：使用 ```` ```mermaid ```` 代码块直接绘制流程图或时序图，图表会自动适配浅色与深色主题：
+
+```mermaid
+graph LR
+  A[Markdown 源文件] --> B[garden sync]
+  B --> C[生成搜索与静态资源]
+  C --> D[页面渲染]
+```
+
+## 6. 写随想（`content/thoughts/*.md`）
+
+随想适合记录短文字、多张配图、本地音视频或外部网页链接卡片：
+
+```yaml
+---
+title: 雨夜调试记录
+date: 2026-10-19 21:30
+tags:
+  - 日常
+media:
+  - type: image
+    src: ./rainy-night/terminal.png
+    alt: 终端里的压测输出
+  - type: link
+    src: https://sqlite.org/wal.html
+    title: SQLite Write-Ahead Logging
+---
+
+记一段简短的想法，支持完整的 Markdown 语法。
+```
+
+`media` 数组支持四类条目：`image`（多张图片自动拼成宫格图集）、`audio`（原生 `<audio>` 音频播放器）、`video`（原生 `<video>` 视频播放器，指向视频文件地址，可配 `poster` 封面）和 `link`（渲染为外部链接卡片，支持 `src`、`title`、`description`、`image`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "app",
     "bin",
     "build",
+    "docs/handbook",
     "public/favicon.svg",
     "public/apple-touch-icon.png",
     "public/og.png",

package/scripts/build-content.mjs

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 import { marked } from "marked";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -19,6 +20,7 @@ import { coverImageSet, loadSharp } from "./cover-images.mjs";
 import { readFileSizeCache } from "./file-sizes.mjs";
 import { previewDocument, previewFileName, renderFilePreview } from "./file-preview.mjs";
 import { parseGardenBlock, parseGardenInfo, scanFences } from "../ui/garden/parse.mjs";
+import { checkGardenMarkdown } from "../ui/garden/check.mjs";
 import {
   fileIcon,
   fileName,
@@ -31,6 +33,8 @@ import {
 import { resolveRepoFile } from "../ui/garden/file-paths.mjs";
 import { trailingSlashEnabled, withTrailingSlash } from "../ui/garden/site-href.mjs";
 
+const gardenPackageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
 function resolveSiteRoot() {
   if (process.env.GARDEN_SITE) return path.resolve(process.env.GARDEN_SITE);
   const yaml = path.join(process.cwd(), "site.config.yaml");
@@ -141,10 +145,12 @@ function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
   if (!value || isExternalAsset(value)) return value;
 
   const baseDir = options.baseDir ?? path.dirname(markdownPath);
+  const allowedRoot = options.allowedRoot ?? contentRoot;
+  const mediaPrefix = options.mediaPrefix ?? "";
   const [assetPath, suffix = ""] = value.split(/(?=[?#])/u, 2);
   const decodedPath = decodeURIComponent(assetPath.replace(/^<|>$/g, ""));
   const absoluteSource = path.resolve(baseDir, decodedPath);
-  const relativeSource = path.relative(contentRoot, absoluteSource);
+  const relativeSource = path.relative(allowedRoot, absoluteSource);
 
   if (
     relativeSource.startsWith("..") ||
@@ -158,7 +164,8 @@ function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
   if (!assetCache.has(absoluteSource)) {
     const extension = path.extname(relativeSource);
     const stem = relativeSource.slice(0, Math.max(0, relativeSource.length - extension.length));
-    const safeRelative = `${stem
+    const prefixedStem = mediaPrefix ? path.join(mediaPrefix, stem) : stem;
+    const safeRelative = `${prefixedStem
       .split(path.sep)
       .map((segment) => segment.replace(/[^\w\u3400-\u9fff.-]+/gu, "-"))
       .join(path.sep)}${extension.toLowerCase()}`;
@@ -173,17 +180,17 @@ function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
   return `${assetCache.get(absoluteSource)}${suffix}`;
 }
 
-function rewriteMarkdownAssets(content, markdownPath, sourcePath) {
+function rewriteMarkdownAssets(content, markdownPath, sourcePath, options = {}) {
   // `![alt](<a b (1).png>)` keeps its angle brackets: without them the space
   // and the parentheses would no longer be one destination.
   const markdownImages = replaceInlineLinks(content, (link) =>
-    link.image ? formatInlineLink(link, copyLocalAsset(link.url, markdownPath, sourcePath)) : undefined,
+    link.image ? formatInlineLink(link, copyLocalAsset(link.url, markdownPath, sourcePath, options)) : undefined,
   );
 
   return markdownImages.replace(
     /(<(?:img|audio|video|source)\b[^>]*\bsrc=["'])([^"']+)(["'])/giu,
     (_, prefix, src, suffix) =>
-      `${prefix}${copyLocalAsset(src, markdownPath, sourcePath)}${suffix}`,
+      `${prefix}${copyLocalAsset(src, markdownPath, sourcePath, options)}${suffix}`,
   );
 }
 
@@ -284,7 +291,9 @@ function rewriteWidgetFences(content, markdownPath, sourcePath) {
 const remoteFileSizes = readFileSizeCache(root).files;
 
 /** One file of a `garden file` fence, resolved for the page. */
-function resolveFileEntry(file, markdownPath, sourcePath) {
+function resolveFileEntry(file, markdownPath, sourcePath, options = {}) {
+  const allowedRoot = options.allowedRoot ?? contentRoot;
+  const assetOptions = options.assetOptions ?? {};
   const src = file.src;
   const name = fileName(src);
   const entry = {
@@ -304,18 +313,18 @@ function resolveFileEntry(file, markdownPath, sourcePath) {
     const size = fs.existsSync(file) && fs.statSync(file).isFile() ? fs.statSync(file).size : 0;
     return { ...entry, url: `${basePath}${src}`, remote: false, preview: "", ...(size > 0 ? { size } : {}) };
   }
-  const resolved = resolveRepoFile(src, markdownPath, contentRoot);
+  const resolved = resolveRepoFile(src, markdownPath, allowedRoot);
   if (resolved.error) fail(sourcePath, `garden file：${resolved.error}`);
   const missingMessage = `garden file 找不到 ${src}；src 相对这篇 Markdown 所在的目录`;
   if (!fs.existsSync(resolved.path) || !fs.statSync(resolved.path).isFile()) fail(sourcePath, missingMessage);
-  const url = copyLocalAsset(src, markdownPath, sourcePath, { missingMessage });
+  const url = copyLocalAsset(src, markdownPath, sourcePath, { ...assetOptions, missingMessage });
   const preview = previewKind(src, { remote: false });
   const next = { ...entry, url, size: fs.statSync(resolved.path).size, remote: false, preview };
   if (preview === "md") {
     // 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));
+    const html = renderFilePreview(rewriteMarkdownAssets(content.trim(), resolved.path, sourcePath, assetOptions));
     const { destination } = assetFiles.get(url.split(/[?#]/u, 1)[0]);
     fs.writeFileSync(previewFileName(destination), previewDocument(html, { title: entry.title }));
     next.previewSrc = previewFileName(url.split(/[?#]/u, 1)[0]);
@@ -328,7 +337,7 @@ function resolveFileEntry(file, markdownPath, sourcePath) {
  * files to the public folder, and replace the YAML with `resolved:` data the
  * page renders without reading the file system.
  */
-function rewriteFileFences(content, markdownPath, sourcePath) {
+function rewriteFileFences(content, markdownPath, sourcePath, options = {}) {
   const fences = scanFences(maskHtmlComments(content)).filter((fence) => parseGardenInfo(fence.info)?.name === "file" && !fence.unclosed);
   if (!fences.length) return content;
   const lines = content.split("\n");
@@ -341,7 +350,7 @@ function rewriteFileFences(content, markdownPath, sourcePath) {
     const resolved = {
       layout: read.layout,
       ...(read.title ? { title: read.title } : {}),
-      files: read.files.map((file) => resolveFileEntry(file, markdownPath, sourcePath)),
+      files: read.files.map((file) => resolveFileEntry(file, markdownPath, sourcePath, options)),
     };
     const indent = " ".repeat(fence.indent);
     lines.splice(
@@ -355,7 +364,7 @@ function rewriteFileFences(content, markdownPath, sourcePath) {
   return lines.join("\n");
 }
 
-function rewriteUiFences(content, markdownPath, sourcePath, lineOffset) {
+function rewriteUiFences(content, markdownPath, sourcePath, lineOffset, assetOptions = {}) {
   const { content: transformed, errors } = transformUiContent(content, {
     mode: uiMode,
     markdownPath: sourcePath.split(path.sep).join("/"),
@@ -364,7 +373,7 @@ function rewriteUiFences(content, markdownPath, sourcePath, lineOffset) {
       const absolute = path.resolve(path.dirname(markdownPath), src);
       return fs.existsSync(absolute) && fs.statSync(absolute).isFile() ? fs.readFileSync(absolute, "utf8") : undefined;
     },
-    resolveAsset: (_sidecarPath, written) => copyLocalAsset(written, markdownPath, sourcePath),
+    resolveAsset: (_sidecarPath, written) => copyLocalAsset(written, markdownPath, sourcePath, assetOptions),
   });
   if (errors.length) {
     fail(
@@ -436,6 +445,9 @@ function validateAndNormalize(data, content, markdownPath, kind, sourcePath, lin
   if (data.draft !== undefined && typeof data.draft !== "boolean") {
     fail(sourcePath, "draft 必须是布尔值");
   }
+  if (data.numbering !== undefined && typeof data.numbering !== "boolean") {
+    fail(sourcePath, "numbering 必须是布尔值");
+  }
 
   if (kind === "post") {
     requireString(data, "description", sourcePath);
@@ -616,6 +628,83 @@ function readColumnReferences(posts) {
   });
 }
 
+const handbookRoot = path.join(gardenPackageRoot, "docs", "handbook");
+
+function readHandbookDocs() {
+  if (!fs.existsSync(handbookRoot)) return [];
+  const assetOptions = { allowedRoot: handbookRoot, mediaPrefix: "garden-docs" };
+  const fileOptions = { allowedRoot: handbookRoot, assetOptions };
+
+  function walk(dir) {
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) return walk(fullPath);
+      if (!entry.name.endsWith(".md")) return [];
+
+      const raw = fs.readFileSync(fullPath, "utf8");
+      const parsed = matter(raw, {
+        engines: {
+          yaml: {
+            parse: (input) => parseYaml(input) ?? {},
+          },
+        },
+      });
+      // Sidecar Markdown attachments (such as docs/handbook/components/file/checklist.md)
+      // do not carry handbook front matter (`section`) and are served as downloadable files.
+      if (!parsed.data || typeof parsed.data.section !== "string") return [];
+      const relativeMd = path.relative(handbookRoot, fullPath).split(path.sep).join("/");
+      const sourcePath = `docs/handbook/${relativeMd}`;
+      const docPath = relativeMd.replace(/\.md$/u, "");
+      const slug = path.basename(fullPath, ".md");
+      const frontMatterLines = raw.slice(0, raw.length - parsed.content.length).split("\n").length - 1;
+      const title = requireString(parsed.data, "title", sourcePath);
+      const description = requireString(parsed.data, "description", sourcePath);
+      const section = requireString(parsed.data, "section", sourcePath);
+      const navTitle = optionalString(parsed.data, "navTitle", sourcePath);
+      const badge = optionalString(parsed.data, "badge", sourcePath);
+      const order = typeof parsed.data.order === "number" ? parsed.data.order : 999;
+      const references = normalizeReferences(parsed.data.references, sourcePath);
+
+      const diagnostics = checkGardenMarkdown(parsed.content.trim(), { title });
+      const blocking = diagnostics.filter((item) => item.severity === "error");
+      if (blocking.length) {
+        fail(
+          sourcePath,
+          blocking.map((item) => `第 ${item.line + frontMatterLines} 行 ${item.code}：${item.message}`).join("；"),
+        );
+      }
+
+      const content = rewriteFileFences(
+        rewriteMarkdownAssets(
+          rewriteUiFences(parsed.content.trim(), fullPath, sourcePath, frontMatterLines + leadingLines(parsed.content), assetOptions),
+          fullPath,
+          sourcePath,
+          assetOptions,
+        ),
+        fullPath,
+        sourcePath,
+        fileOptions,
+      );
+
+      return [{
+        title,
+        slug,
+        ...(navTitle ? { navTitle } : {}),
+        description,
+        path: docPath,
+        section,
+        order,
+        ...(badge ? { badge } : {}),
+        ...(references ? { references } : {}),
+        sourcePath,
+        content,
+      }];
+    });
+  }
+
+  return walk(handbookRoot).sort((a, b) => a.order - b.order || a.path.localeCompare(b.path));
+}
+
 fs.rmSync(generatedMediaRoot, { recursive: true, force: true });
 
 const posts = readMarkdownTree(path.join(contentRoot, "posts"), "post").sort(
@@ -627,6 +716,9 @@ const columns = readColumnReferences(posts).sort(
 const thoughts = readMarkdownTree(path.join(contentRoot, "thoughts"), "thought").sort(
   (a, b) => Date.parse(b.date) - Date.parse(a.date),
 );
+const allHandbookDocs = readHandbookDocs();
+const gardenIndexDoc = allHandbookDocs.find((doc) => doc.path === "index") ?? null;
+const gardenDocs = allHandbookDocs.filter((doc) => doc.path !== "index");
 
 // Intrinsic image sizes for width/height on <img>: local files are read now,
 // remote ones come from image-sizes.json (written by scripts/image-sizes.mjs).
@@ -647,7 +739,7 @@ function localImageFile(src) {
 }
 const remoteImageSizes = readImageCache(root).images;
 const imageSizes = {};
-for (const entry of [...posts, ...columns, ...thoughts]) {
+for (const entry of [...posts, ...columns, ...thoughts, ...allHandbookDocs]) {
   for (const src of imageSources(entry.content)) {
     if (imageSizes[src]) continue;
     if (/^https?:\/\//iu.test(src)) {
@@ -670,6 +762,7 @@ assertUnique(
   "专栏文章顺序",
 );
 assertUnique(thoughts, (item) => item.slug, "随想 slug");
+assertUnique(gardenDocs, (item) => item.path, "Garden 文档路径");
 
 const parityDir = path.join(root, "parity", "articles");
 const a2WordCounts = fs.existsSync(parityDir)
@@ -721,6 +814,7 @@ export type ContentEntry = {
   tags?: string[];
   references?: { title: string; url?: string; domain?: string }[];
   pinned?: boolean;
+  numbering?: boolean;
   readingTime?: string;
   kind: "post" | "column" | "thought";
   sourcePath: string;
@@ -742,6 +836,18 @@ export type ContentEntry = {
   linkDescription?: string;
 };
 
+export type GardenDocEntry = {
+  title: string;
+  navTitle?: string;
+  description: string;
+  path: string;
+  section: string;
+  order: number;
+  badge?: string;
+  references?: { title: string; url?: string; domain?: string }[];
+  content: string;
+};
+
 export type LinkCardMeta = { title: string; description?: string; siteName?: string; author?: string; publishedTime?: string; image?: string };
 export type LinkAssets = { favicons: Record<string, string>; cards: Record<string, LinkCardMeta> };
 
@@ -749,6 +855,8 @@ export const contentHash = "${contentHash}";
 export const posts = ${JSON.stringify(posts, null, 2)} as ContentEntry[];
 export const columns = ${JSON.stringify(columns, null, 2)} as ContentEntry[];
 export const thoughts = ${JSON.stringify(thoughts, null, 2)} as ContentEntry[];
+export const gardenDocs = ${JSON.stringify(gardenDocs, null, 2)} as GardenDocEntry[];
+export const gardenIndexDoc = ${JSON.stringify(gardenIndexDoc, null, 2)} as GardenDocEntry | null;
 export const a2WordCounts = ${JSON.stringify(a2WordCounts, null, 2)} as Record<string, number>;
 export const linkAssets = ${JSON.stringify(linkAssetsForRender(root, basePath), null, 2)} as LinkAssets;
 export const imageSizes: Record<string, { width: number; height: number }> = ${JSON.stringify(imageSizes)};
@@ -839,7 +947,8 @@ writeRssFeed(
   posts.map((entry) => feedEntry(entry, `/blog/${entry.path}/`)),
 );
 const sitemapEntries = [
-  "/", "/blog/", "/thoughts/", "/columns/", "/about/",
+  "/", "/blog/", "/thoughts/", "/columns/", "/about/", "/garden/",
+  ...gardenDocs.map((entry) => `/garden/${entry.path}/`),
   ...posts.map((entry) => `/blog/${entry.path}/`),
   ...columns.map((entry) => `/columns/${entry.column}/${columnEntryPath(entry)}/`),
   ...thoughts.map((entry) => `/thoughts/${entry.slug}/`),

package/scripts/handbook-allowlist.mjs

@@ -0,0 +1,68 @@
+/**
+ * Small explicit allowlist for the handbook fact-check gate.
+ * Only external tools or standard non-Garden tokens that cannot be derived
+ * from repository source files belong here. Every entry requires a comment.
+ */
+
+export const ALLOWED_EXTERNAL_BINARIES = {
+  // Node.js package manager used to install hd-garden and run package scripts
+  npm: "Node.js package manager CLI",
+  // Node.js package runner used to invoke `npx garden` / `npx hd-garden`
+  npx: "Node.js package runner CLI",
+  // Node.js runtime CLI
+  node: "Node.js runtime CLI",
+  // Git version control CLI used in authoring and deployment workflows
+  git: "Git CLI",
+  // POSIX shell builtin for changing the working directory
+  cd: "POSIX shell directory builtin",
+  // OpenSSH key generator used when creating a GitHub Pages deploy key
+  "ssh-keygen": "OpenSSH key generation tool for deploy keys",
+};
+
+export const ALLOWED_EXTERNAL_FLAGS = {
+  // `npm install --save-exact` pins the exact hd-garden version in a site repo
+  "--save-exact": "npm install flag to pin exact dependency version",
+  // `ssh-keygen -t ed25519 -C ... -f ...` standard OpenSSH flags
+  "-t": "ssh-keygen key type flag",
+  "-C": "ssh-keygen comment flag",
+  "-f": "ssh-keygen output file flag",
+  // `git commit -m` / `git add -A` standard git flags
+  "-m": "git commit message flag",
+  "-A": "git add all tracked/untracked files flag",
+};
+
+export const ALLOWED_NON_ENV_UPPER_SNAKE = {
+  // Placeholder token shown in ssh-keygen / GitHub Actions prose or HTTP/DOM acronyms
+  GFM: "GitHub Flavored Markdown acronym",
+  YAML: "YAML Ain't Markup Language acronym",
+  HTML: "HyperText Markup Language acronym",
+  CSS: "Cascading Style Sheets acronym",
+  SVG: "Scalable Vector Graphics acronym",
+  JSON: "JavaScript Object Notation acronym",
+  CSV: "Comma-Separated Values acronym",
+  TSV: "Tab-Separated Values acronym",
+  URL: "Uniform Resource Locator acronym / Makefile URL parameter",
+  RSS: "Really Simple Syndication acronym",
+  TOC: "Table of Contents acronym",
+  CJK: "Chinese, Japanese, Korean typography acronym",
+  LIGHT: "Theme label in prose/diagrams",
+  DARK: "Theme label in prose/diagrams",
+  UTF: "Unicode Transformation Format prefix",
+  DOM: "Document Object Model acronym",
+  HTTP: "Hypertext Transfer Protocol acronym",
+  HTTPS: "Hypertext Transfer Protocol Secure acronym",
+  SSH: "Secure Shell acronym",
+  PAT: "Personal Access Token acronym",
+  OAuth: "Open Authorization acronym",
+  API: "Application Programming Interface acronym",
+  CDN: "Content Delivery Network acronym",
+  DNS: "Domain Name System acronym",
+  CI: "Continuous Integration acronym",
+  PR: "Pull Request acronym",
+  ID: "Identifier acronym",
+  UI: "User Interface acronym",
+  AI: "Artificial Intelligence acronym",
+  MB: "Megabyte unit",
+  KB: "Kilobyte unit",
+  GB: "Gigabyte unit",
+};