hd-garden 0.7.0 → 0.8.0

package/docs/handbook/en/workflow.md

@@ -0,0 +1,81 @@
+---
+title: Checks & Shortcuts
+navTitle: Checks & Shortcuts
+description: Validate posts and diagnostic codes with npx garden check, install the Git pre-commit hook, and use editor snippets and Agent skills.
+section: workflow
+order: 40
+---
+
+To catch YAML indentation mistakes, missing required fields, or broken local file paths before publishing, Garden ships a CLI validator, a Git pre-commit hook, snippet templates, and bundled Agent skills.
+
+## 1. Validation Commands
+
+Three commands check your content at different scopes:
+
+- **Check one or more posts (`npx garden check`)**:
+  ```bash
+  npx garden check content/posts/my-post.md
+  # Or pass multiple Markdown files at once
+  npx garden check content/posts/*.md
+  ```
+- **Check interactive blocks and component syntax (`npx garden ui check`)**:
+  ```bash
+  npx garden ui check content/posts/my-post.md
+  # Check staged Markdown files in Git
+  npx garden ui check --staged
+  # Check all Markdown files in the repository
+  npx garden ui check --all
+  ```
+- **Sync and build the entire site (`make check`)**:
+  ```bash
+  make check
+  ```
+  In the site `Makefile`, `make check` runs `npx garden sync && npx garden build` to execute full content synchronization, component validation, and the production build.
+
+## 2. `npx garden check` Diagnostic Codes
+
+`npx garden check` (backed by `scripts/check-post.mjs`, `ui/garden/check.mjs`, and `ui/garden/file-paths.mjs`) reports exact line numbers, diagnostic codes, and fix suggestions:
+
+| Code | Severity | Cause and Fix |
+| :--- | :--- | :--- |
+| `missing-title` / `missing-description` | Error | Front Matter is missing a non-empty `title` or `description` |
+| `unexpected-slug` | Error | Front Matter includes a manual `slug` field (remove `slug`; the filename is the slug) |
+| `date-format` | Error | `date` is not a valid `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or ISO timestamp with timezone |
+| `missing-cover` / `missing-asset` | Error | A local file referenced by `cover`, a Markdown image, or `garden file` does not exist |
+| `heading-h1` / `heading-skip` | Error | The post body uses an `#` H1 heading or skips a heading level (such as jumping from `##` to `####`) |
+| `reference-heading` | Error | The post body contains a references section heading (move references to the `references` Front Matter list) |
+| `callout-type` | Error | `> [!TYPE]` uses an unsupported callout type |
+| `title-split` | Warning | The title contains a split delimiter with an empty left or right side |
+| `diff-orphan` | Error | A `diff` code fence is not immediately preceded by a complete code block |
+| `legacy-fence` | Error | Uses a legacy fence name (such as `garden:stat`, `widget`, `embed`, or `html garden`); replace with `garden <name>` |
+| `garden-idea` | Error | A non-draft post still contains an uncompiled `garden` idea fence |
+| `garden-name` | Error | Unknown `garden` component name (must be `card`, `stat`, `compare`, `timeline`, `chart`, `figure`, `html`, `interactive`, or `file`) |
+| `garden-yaml` | Error | Invalid YAML syntax, wrong top-level shape, or unsupported keys inside a `garden` fence |
+| `garden-file` / `file-outside` | Error | `garden file` manually sets `resolved`, is missing a valid `src` / `files`, or points outside `content/` |
+| `file-large` | Warning | A local file referenced by `garden file` exceeds `5 MB` |
+| `compare-long` | Error | A single cell in `garden compare` exceeds roughly 60 characters |
+| `interactive-trivial` / `steps-prose` | Error | `garden interactive` only computes a single multiplication, or `<Steps>` contains only prose without state changes |
+
+## 3. Git Pre-commit Hook and Component Catalog
+
+- **Install the pre-commit hook**: Run `npx garden hooks` to write `.git/hooks/pre-commit`, which runs `npx --no-install garden ui check --staged --quiet` on every `git commit`:
+  ```bash
+  npx garden hooks
+  ```
+- **Generate the local component catalog**: Run `npx garden ui catalog` to write a static preview page of all built-in components to `.garden/ui-catalog.html`:
+  ```bash
+  npx garden ui catalog
+  ```
+
+## 4. Component Templates, Snippets, and Agent Skills
+
+Garden provides three ways to insert or generate components quickly:
+
+1. **Draft cheat sheet comment**: Running `make new SLUG=xxx TITLE="..."` appends an HTML comment to the bottom of the new `.md` file with examples for idea fences and all 9 components. HTML comments are hidden from the rendered page and can be deleted when finished.
+2. **Snippet template files**: The `templates/` directory inside `hd-garden` includes two template files:
+   - `templates/garden-blocks.md`: Copyable Markdown templates for idea fences and all 9 built-in components.
+   - `templates/garden-snippets.plist`: macOS text replacements (drag into **System Settings → Keyboard → Text Replacements**) with triggers `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gfigure`, `;ghtml`, `;ginteractive`, and `;gfile`.
+3. **Install AI Agent skills (`npx garden skill`)**: Running `npx garden skill` in a site repository (also run automatically during `npx hd-garden init`) copies three skills into `.agents/skills/`:
+   - `garden-ui`: Compiles natural-language `garden` idea fences into concrete component blocks.
+   - `garden-interactive-chart`: Authors `interactive`, `chart`, `figure`, and `html` components from article data.
+   - `garden-post-review`: Reviews an entire post against layout and component rules.

package/docs/handbook/en/writing.md

@@ -0,0 +1,156 @@
+---
+title: Writing Posts & Thoughts
+navTitle: Writing Posts & Thoughts
+description: Front Matter fields for posts and thoughts, code diff toggles, callouts, link cards, math formulas, and Mermaid diagrams.
+section: writing-and-reading
+order: 10
+---
+
+Garden organizes content into **posts** (`content/posts/`) and **thoughts** (`content/thoughts/`). Both are UTF-8 Markdown files whose filenames contain only lowercase letters, digits, and hyphens (`a-z`, `0-9`, `-`).
+
+## 1. Post Front Matter (`content/posts/*.md`)
+
+Create a post with `make new DIR=systems SLUG=wal-checkpoint TITLE="Understanding WAL | Checkpoints and Recovery"` or create a `.md` file directly:
+
+```yaml
+---
+title: Understanding WAL | Checkpoints and Recovery
+date: 2026-10-18
+updated: 2026-10-19
+description: How write-ahead logging preserves snapshot visibility under concurrent reads and writes, and how background checkpoints bound log growth.
+tags:
+  - Database
+  - Storage
+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
+---
+```
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `title` | Yes | String | Post title. Write ` \| ` (with spaces on both sides) to split the heading into two lines and scale the font size to fit |
+| `date` | Yes | Date string | Publication date (such as `2026-10-18` or an ISO timestamp with timezone) |
+| `description` | Yes | String | Summary shown in the article deck, archive lists, and search engine descriptions |
+| `updated` | No | Date string | Last updated date, shown in the article meta bar and used for RSS sorting |
+| `publishAt` | No | Date string | Scheduled publish time; included only when earlier than the build time (or when `CONTENT_INCLUDE_DRAFTS=1`) |
+| `tags` | No | String array | Tags for the post; clicking a tag filters `/blog?t=<tag>` |
+| `pinned` | No | Boolean | Set to `true` to feature the post in the pinned section on the home page |
+| `draft` | No | Boolean | Set to `true` to mark as a draft and exclude from production builds |
+| `cover` | No | Path string | Cover image path relative to `content/covers/` |
+| `original` | No | Full URL | External canonical source link, rendered in the article meta bar |
+| `references` | No | `{ title, url? }[]` | Reference list rendered at the bottom of the post with automatically extracted domain names |
+
+At the bottom of every post page, between the Webmention section and the comments, sit the Previous and Next navigation cards. Posts link only to other posts ordered by `date` (where Previous is the older post), while column entries follow their order in `content/columns.yaml`; the oldest and newest entries show only one card.
+
+> [!CAUTION] Caution
+> Do not write a `slug` field in Front Matter (`npx garden check` reports an `unexpected-slug` error because the filename is already the slug). Posts do not use a `topic` field either.
+
+## 2. Code Blocks and the Diff Toggle
+
+Standard code blocks show their language label (such as `RUST`, `TS`, `PYTHON`, or `SHELL`) and a copy button in the top-right corner. To show how a snippet changed from an earlier version, place the updated code block first and follow it with a `garden` idea fence stating what changed in one sentence:
+
+````markdown
+```go
+func openStore(path string) (*Store, error) {
+	return openWithMode(path, ModeWAL)
+}
+```
+
+```garden
+Compared with the previous version: open the store with ModeWAL instead of ModeJournal.
+```
+````
+
+Following the `garden-ui` skill, the Agent runs `npx garden ui apply` to replace that idea fence with a `diff` fence right below the code block (see [Writing with AI](/garden/en/ai-writing)). The page combines the two adjacent blocks into a single code frame with tabs for the full code and the diff against the previous version, while the copy button always copies the new full code:
+
+```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)
+ }
+```
+
+**Hand-written format**: Without an Agent, you can write the `diff` code block directly below the complete code block (separated only by a blank line):
+
+````markdown
+```diff
+ func openStore(path string) (*Store, error) {
+-	return openWithMode(path, ModeJournal)
++	return openWithMode(path, ModeWAL)
+ }
+```
+````
+
+> [!IMPORTANT] Important
+> A `diff` fence must immediately follow a complete code block; a standalone `diff` fence with no preceding code block triggers a `diff-orphan` error in `npx garden check`.
+
+## 3. CJK Bold, Highlighter Strokes, and Callouts
+
+- **CJK-friendly bold**: `remark-cjk-friendly` is enabled so `**bold next to CJK punctuation**` parses cleanly without extra spaces around the asterisks.
+- **Highlighter stroke**: Wrap text in `<u>key phrase</u>` or `<mark>key phrase</mark>` to apply a warm yellow highlighter band, like <u>this highlighted phrase</u>.
+- **Callouts**: Supports `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, and `> [!CAUTION]` (plus `INFO`, `SUCCESS`, `DANGER`, and `FAILURE`). Write a title on the same line after the marker to set a custom heading:
+
+```markdown
+> [!WARNING] Back Up the Data Directory Before Upgrading
+> Changing the page size requires rebuilding the index files and cannot be rolled back in place.
+```
+
+> [!WARNING] Back Up the Data Directory Before Upgrading
+> Changing the page size requires rebuilding the index files and cannot be rolled back in place.
+
+## 4. Local Images and External Link Cards
+
+- **Local images and sidecar folders**: For a post at `content/posts/my-post.md`, place its images inside `content/posts/my-post/` and reference them with relative paths such as `./my-post/diagram.svg`. At build time, Garden copies the file, records its pixel dimensions, and renders the `alt` text (unless it starts with default placeholders like `image` or `img`) as a `<figcaption>`.
+- **Inline external links**: External links in body text automatically display the target site's favicon and keep the icon attached to the first word of the link so it never wraps alone.
+- **Link cards**: Turn an external URL into a preview card with site name, title, and description in either of two ways:
+  1. Put the full URL on its own paragraph line (surrounded by blank lines): `https://spec.commonmark.org/`
+  2. Append `{card}` directly to an inline link (with no space): `See the [CommonMark Spec](https://spec.commonmark.org/){card}.`
+  You can also run `make embed URL="https://example.com"` to fetch Open Graph metadata for a URL.
+
+## 5. Math Formulas and Mermaid Diagrams
+
+- **LaTeX math**: Rendered at build and server-render time with KaTeX. Use `$L = \lambda W$` for inline math and `$$...$$` for display blocks. Multi-letter identifiers containing underscores (such as `group_num` or `max_batch`) are automatically wrapped as upright `\mathrm{group\_num}`, while single-letter subscripts like `W_q` or `H_{kv}` remain standard math subscripts.
+- **Mermaid diagrams**: Use ```` ```mermaid ```` fences to draw flowcharts or sequence diagrams that adapt to light and dark themes:
+
+```mermaid
+graph LR
+  A[Markdown Source] --> B[garden sync]
+  B --> C[Search & Static Assets]
+  C --> D[Rendered Page]
+```
+
+## 6. Writing Thoughts (`content/thoughts/*.md`)
+
+Thoughts are short notes with optional image grids, audio/video files, or external link cards:
+
+```yaml
+---
+title: Late-Night Debugging Notes
+date: 2026-10-19 21:30
+tags:
+  - Notes
+media:
+  - type: image
+    src: ./rainy-night/terminal.png
+    alt: Benchmark output in the terminal
+  - type: link
+    src: https://sqlite.org/wal.html
+    title: SQLite Write-Ahead Logging
+---
+
+A short note written in standard Markdown.
+```
+
+The `media` array accepts four item types: `image` (multiple images automatically form a grid), `audio` (native `<audio>` player), `video` (native `<video>` player with optional `poster`), and `link` (rendered as an external link card supporting `src`, `title`, `description`, and `image`).

package/docs/handbook/index.md

@@ -5,11 +5,106 @@ section: overview
 order: 0
 ---
 
-长篇技术文章除了段落，常常还有架构图、多列对比和改过的代码。在 Garden 里这些都用普通 Markdown 写，排版交给构建流程和页面脚本。下面每一节都附带实际效果。
+Garden 是一个 Claude 风格的博客框架，文章用 Markdown 写，组件用自然语言描述就行。
+
+## 一个完整的例子
+
+下面四步是同一篇稿子的真实过程，命令输出均来自实际运行结果。
+
+### 1. 作者写一句想法
+
+在想放交互的地方写一个不带名字的 `garden` 围栏，里面写清想让读者做什么、看到什么：
+
+````markdown
+## 写作节奏
+
+```garden
+让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
+```
+````
+
+### 2. Agent 扫描并写回组件
+
+对 Agent 说「编译这篇：content/posts/writing-pace.md」。Agent 按站点里的 `garden-ui` skill 先运行 `npx garden ui scan`，拿到这一块的行号、原话和哈希：
+
+```console
+$ npx garden ui scan content/posts/writing-pace.md
+{
+  "file": "content/posts/writing-pace.md",
+  "draft": false,
+  "blocks": [
+    {
+      "lang": "garden-idea",
+      "status": "uncompiled",
+      "startLine": 9,
+      "intentHash": "cb3a3569",
+      "intent": "让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。",
+      "section": "写作节奏"
+    }
+  ]
+}
+```
+
+接着 Agent 读取 `npx garden ui prompt` 里的组件目录，写出 `garden interactive`，再用 `npx garden ui apply` 按 `--intent-hash` 只替换这一块，围栏外的正文逐字节不变：
+
+```console
+$ npx garden ui apply content/posts/writing-pace.md --intent-hash cb3a3569 --file new.md
+{"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}
+```
+
+### 3. 提交前钩子检查并生成修复提示词
+
+首次运行 `garden sync` 或 `garden dev` 时，Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`。如果作者在第 2 步之前直接提交，钩子会拦下提交，并打印一段可以直接粘贴给 AI 的修复提示词：
+
+```console
+$ git commit -m "写作节奏"
+content/posts/writing-pace.md:9  -  garden-idea  还有没编译的想法
+
+──────────────────────── 发给 AI 的修复提示词 ────────────────────────
+请处理下面 Garden 博文里列出的块：没编译的想法要编译，有错误的交互块要修好。
+
+要求：
+- 先运行 npx garden ui prompt，读组件目录和规则；仓库里有 garden-ui skill 时按它的流程做。
+- 只改列出的块，用 npx garden ui apply <稿件> --id <id> 写回（没有 id 的想法用 --intent-hash），不要直接编辑稿件。
+- 不改作者原话的意思。改完运行 npx garden ui check <稿件>，直到通过。
+- 如果你不能访问这个仓库，就只回复每块修好后的完整围栏。
+
+1. content/posts/writing-pace.md，第 9–11 行，intent-hash: cb3a3569
+   - garden-idea：这段想法还没编译，请按原话编译成 garden interactive 或其他 garden 组件（或判断后写回正文）。
+（后面附当前围栏原文）
+────────────────────────────────────────────────────────────
+已写入 .garden/ui-fix-prompt.md。确实要先提交，可以用 git commit --no-verify。
+```
+
+这段提示词同时写入 `.garden/ui-fix-prompt.md`，有剪贴板命令时自动复制。把提示词贴给 Agent 完成转换后再提交，钩子静默通过（退出码 `0`）。
+
+### 4. 页面渲染结果
+
+第 2 步写回的 `garden interactive` 块在文章页面直接渲染为可拖动的交互控件：
+
+```garden interactive #writing-pace
+caption: 每天多写几百字，比每周多写一天更快。
+intent: |
+  让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
+---
+<State daily={500} days={3} />
+<Let weekly={daily * days} />
+<Let weeks={ceil(8000 / weekly)} />
+
+<Slider bind="daily" label="每天写" min={200} max={2000} step={100} unit="字" />
+<Slider bind="days" label="每周写" min={1} max={7} step={1} unit="天" />
+
+<Stat label="写完 8000 字需要" value={weeks} unit="周" hint="不足一周按一周算" />
+```
+
+> [!IMPORTANT] 人和 Agent 用同一套工具
+> Agent 找块用的 `npx garden ui scan`、写回用的 `npx garden ui apply`、自查用的 `npx garden ui check`，和作者提交时 pre-commit 钩子运行的检查是同一组命令。钩子拦截时打印的提示词，就是发给 Agent 的下一步指令。详见 [用 AI 写作](/garden/ai-writing)。
+
+下面几节介绍不用 Agent 也会自动生效的版面与组件规则。
 
 ## 标题分行与 `740px` 正文列
 
-上方的标题在 `丨` 处分成两行，字号按较长一行自动计算。正文保持在 `740px` 阅读列内，宽图会在两侧留白里对称外扩，不会盖住导航和目录。
+标题里写一个「丨」，就在那里分成两行，字号按较长一行自动计算。正文保持在 `740px` 阅读列内，宽图会在两侧留白里对称外扩，不会盖住导航和目录。
 
 下面这张透明底的线稿在深色模式下会自动垫上暖白底，不用另做一套配图：
 
@@ -27,7 +122,7 @@ order: 0
 
 ## 代码块与「对比上一版」切换
 
-把改好的完整代码块和一段 `diff` 紧挨着写，页面会把它们合成一个可以切换「代码」和「对比上一版」的代码框。复制按钮复制的总是新版完整代码。
+在改好的完整代码下面写一句想法说明和上一版比改了什么，Agent 会生成一段紧挨着的 `diff` 代码块；你也可以直接手写 `diff`。完整代码和 `diff` 紧挨着时，页面会把它们合成一个可切换「代码」和「对比上一版」的代码框，复制按钮始终复制新版完整代码。
 
 ```yaml
 pages:

package/docs/handbook/writing.md

@@ -46,14 +46,14 @@ references:
 | `original` | 否 | 完整链接 | 原文链接，设置后在标题下方元信息栏显示 `原文 ↗` |
 | `references` | 否 | `{ title, url? }[]` | 文末参考资料列表，构建期自动提取域名并渲染在正文底部的「参考」卡片中 |
 
+文章页底部，在「来自开放网络的回应」和评论之间，有「上一篇」「下一篇」两个按钮。长文只和长文排，按 `date` 先后，上一篇是更早的那篇；专栏文章按专栏里的顺序排；最早或最新的一篇只显示一侧。
+
 > [!CAUTION]
 > 不要在 Front Matter 里手写 `slug` 字段（`npx garden check` 会报 `unexpected-slug` 错误：`不要写 slug，文件名就是标识`）。文章也没有 `topic` 分类字段。
 
 ## 2. 代码块与「代码 / 对比上一版」切换
 
-普通代码块在右上角带有语言名称（如 `RUST`、`TS`、`PYTHON`、`SHELL`）和复制按钮。
-
-如果你想展示某段代码修改前后的对比，**先放一段完整代码块，紧接着放一段 `diff` 代码块**。渲染器会自动把它们合并成一个带 **「代码」** 和 **「对比上一版」** 两个切换按钮的代码框：
+普通代码块在右上角带有语言名称（如 `RUST`、`TS`、`PYTHON`、`SHELL`）和复制按钮。想展示一段代码和上一版相比改了什么，先放改好的完整代码，再紧跟着写一个 `garden` 想法块，用一句话写出改动内容：
 
 ````markdown
 ```go
@@ -62,15 +62,12 @@ func openStore(path string) (*Store, error) {
 }
 ```
 
-```diff
- func openStore(path string) (*Store, error) {
--	return openWithMode(path, ModeJournal)
-+	return openWithMode(path, ModeWAL)
- }
+```garden
+和上一版比：打开存储时的模式从 ModeJournal 改成了 ModeWAL。
 ```
 ````
 
-实际渲染效果如下（点击右上角的 **「代码」** 与 **「对比上一版」** 可以切换，点击复制按钮始终复制前面的完整代码）：
+Agent 按 `garden-ui` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏（详见 [用 AI 写作](/garden/ai-writing)）。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框，右上角的复制按钮始终复制新版完整代码：
 
 ```go
 func openStore(path string) (*Store, error) {
@@ -85,8 +82,19 @@ func openStore(path string) (*Store, error) {
  }
 ```
 
+**手写格式**：如果不使用 Agent，也可以直接在完整代码块正下方手写一段 `diff` 代码块（两段之间只隔空行）：
+
+````markdown
+```diff
+ func openStore(path string) (*Store, error) {
+-	return openWithMode(path, ModeJournal)
++	return openWithMode(path, ModeWAL)
+ }
+```
+````
+
 > [!IMPORTANT]
-> `diff` 代码块前面必须紧挨着一段完整代码块（中间只能隔空行）；如果单独放一段 `diff` 而前面没有完整代码块，`npx garden check` 会报 `diff-orphan` 错误。
+> `diff` 代码块必须紧跟在一段完整代码块后面；如果单独写一段 `diff` 而前面没有完整代码，`npx garden check` 会报 `diff-orphan` 错误。
 
 ## 3. 中文加粗、荧光笔高亮与提示框
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/build-content.mjs

@@ -716,9 +716,20 @@ 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");
+// docs/handbook/en/** mirrors the Chinese handbook page for page: the same
+// relative path is the counterpart. Each entry carries its lang; English paths
+// drop the en/ prefix and are served under /garden/en/.
+const allHandbookDocs = readHandbookDocs().map((doc) =>
+  doc.path === "en" || doc.path.startsWith("en/")
+    ? { ...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 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;
+const gardenDocsEn = enHandbookDocs.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).
@@ -762,7 +773,12 @@ assertUnique(
   "专栏文章顺序",
 );
 assertUnique(thoughts, (item) => item.slug, "随想 slug");
+// /thoughts/page/<n>/ holds the static pages of the feed.
+for (const thought of thoughts) {
+  if (thought.slug === "page") fail(thought.sourcePath ?? "content/thoughts/page.md", "随想不能叫 page：/thoughts/page/ 留给分页");
+}
 assertUnique(gardenDocs, (item) => item.path, "Garden 文档路径");
+assertUnique(gardenDocsEn, (item) => item.path, "Garden English handbook path");
 
 const parityDir = path.join(root, "parity", "articles");
 const a2WordCounts = fs.existsSync(parityDir)
@@ -857,6 +873,8 @@ 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 gardenDocsEn = ${JSON.stringify(gardenDocsEn, null, 2)} as GardenDocEntry[];
+export const gardenIndexDocEn = ${JSON.stringify(gardenIndexDocEn, 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)};
@@ -949,6 +967,8 @@ writeRssFeed(
 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}/`),

package/scripts/handbook-facts.mjs

@@ -1055,6 +1055,39 @@ export function checkFileFacts(filePath, content, facts, root = ROOT) {
   return issues;
 }
 
+/**
+ * English pages mirror the Chinese ones: docs/handbook/en/<path>.md must have
+ * docs/handbook/<path>.md with the same section and order. Chinese pages without
+ * an English twin are fine (not translated yet).
+ */
+export function checkHandbookPairs(root = ROOT) {
+  const handbook = path.join(root, "docs/handbook");
+  const enRoot = path.join(handbook, "en");
+  const issues = [];
+  const head = (text) => {
+    const m = text.match(/^---\n([\s\S]*?)\n---/u);
+    const field = (key) => m?.[1].match(new RegExp(`^${key}:\\s*(.+)$`, "mu"))?.[1].trim();
+    return { section: field("section"), order: field("order") };
+  };
+  for (const file of walkFiles(enRoot, (f) => f.endsWith(".md"))) {
+    const rel = path.relative(enRoot, file);
+    const zhFile = path.join(handbook, rel);
+    const relEn = path.relative(root, file).replace(/\\/g, "/");
+    if (!fs.existsSync(zhFile)) {
+      issues.push({ file: relEn, line: 1, kind: "handbook-pair", message: `no Chinese counterpart docs/handbook/${rel.replace(/\\/g, "/")}` });
+      continue;
+    }
+    const en = head(fs.readFileSync(file, "utf8"));
+    const zh = head(fs.readFileSync(zhFile, "utf8"));
+    for (const key of ["section", "order"]) {
+      if (en[key] !== zh[key]) {
+        issues.push({ file: relEn, line: 1, kind: "handbook-pair", message: `${key} is ${en[key] ?? "missing"}, the Chinese page has ${zh[key] ?? "missing"}` });
+      }
+    }
+  }
+  return issues;
+}
+
 /**
  * Scan all docs/handbook/ and app/garden/ files and return any fact-check failures.
  */
@@ -1069,6 +1102,7 @@ export function checkAllHandbookFacts(root = ROOT) {
     const content = fs.readFileSync(file, "utf8");
     issues.push(...checkFileFacts(file, content, facts, root));
   }
+  issues.push(...checkHandbookPairs(root));
   const svgFiles = walkFiles(path.join(root, "docs/handbook"), (f) => f.endsWith(".svg"));
   for (const svgFile of svgFiles) {
     const svgContent = fs.readFileSync(svgFile, "utf8");

package/scripts/html-lang.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/** Static export: English handbook pages get <html lang="en"> (ui/garden/html-lang.mjs). */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { handbookHtmlLang, withHtmlLang } from "../ui/garden/html-lang.mjs";
+
+/** Rewrites every .html under root whose path is an English handbook page; returns the relative paths. */
+export function setHandbookHtmlLang(root) {
+  const changed = [];
+  const visit = (directory) => {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.name.endsWith(".html")) {
+        const relative = path.relative(root, absolute).split(path.sep).join("/");
+        const lang = handbookHtmlLang(relative);
+        if (!lang || relative.includes("/media/") || relative.startsWith("media/")) continue;
+        const html = fs.readFileSync(absolute, "utf8");
+        const next = withHtmlLang(html, lang);
+        if (next !== html) {
+          fs.writeFileSync(absolute, next);
+          changed.push(relative);
+        }
+      }
+    }
+  };
+  visit(root);
+  return changed.sort();
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  setHandbookHtmlLang(path.join(siteRoot, "dist", "client"));
+}

package/scripts/static-404.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Static export with a basePath: vinext writes 404.html at dist/client/404.html.
+ * Copy it into the basePath folder too, so a host that serves only that folder
+ * (or Paths under /basePath/…) still has a 404 page next to the site.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function copyNotFoundIntoBasePath(clientRoot, basePath = "") {
+  const base = String(basePath ?? "").replace(/\/+$/u, "").replace(/^\/+/u, "");
+  if (!base) return null;
+  const source = path.join(clientRoot, "404.html");
+  const destination = path.join(clientRoot, base, "404.html");
+  if (!fs.existsSync(source) || !fs.existsSync(path.dirname(destination))) return null;
+  fs.copyFileSync(source, destination);
+  return path.relative(clientRoot, destination).split(path.sep).join("/");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  const basePath = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/u, "");
+  copyNotFoundIntoBasePath(path.join(siteRoot, "dist", "client"), basePath);
+}