hd-garden 0.6.1 → 0.8.0

package/.agents/skills/garden-ui/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: garden-ui
 description: >-
-  Compiles the intent blocks in one Garden post into ui blocks (or prose, or
-  garden html), recompiles stale or broken ui blocks, and suggests where a post
-  could use interaction. Use when the user says 编译这篇 / 编译意图块 / 重编译
-  <id> / 这篇哪里适合交互, or pastes a garden ui check fix prompt.
+  Compiles the `garden` idea blocks in one Garden post into garden components
+  (garden interactive, or card / stat / compare / ... , or prose, or garden
+  html), fixes broken garden interactive blocks, and suggests where a post could
+  use interaction. Older intent / ui blocks are handled the same way. Use when
+  the user says 编译这篇 / 编译想法 / 重编译 <id> / 这篇哪里适合交互, or pastes a
+  garden ui check fix prompt.
 ---
 
 # 编译 Garden 交互块
 
-作者在稿里用 `intent` 围栏写一句想法，这个 skill 把它变成 `ui` 块。`ui` 块的格式、组件和设计规则都在 `npx garden ui prompt` 的输出里，以那份为准，不凭记忆写组件。
+作者在稿里用不带名字的 `garden` 围栏写一句想法，这个 skill 把它变成 `garden interactive` 或别的 `garden` 组件。交互组件和设计规则在 `npx garden ui prompt` 的输出里，9 个 `garden` 组件的用途和示例在 `node_modules/hd-garden/templates/garden-blocks.md`（在引擎仓库里是 `templates/garden-blocks.md`），以这两份为准，不凭记忆写组件。
+
+作者提交时，提交前钩子跑的是同一个 `npx garden ui check`。你用来找块、写回、自查的命令，和拦住作者提交的命令是同一套。
 
 所有命令在站点根目录运行。没给稿件路径时只问路径，不扫全库。
 
@@ -17,7 +21,7 @@ description: >-
 
 | 用户说 | 处理哪些块 |
 | --- | --- |
-| 编译这篇：`<路径>`、编译意图块 | 状态是 `uncompiled`、`stale`、`error` 的块 |
+| 编译这篇：`<路径>`、编译想法 | 状态是 `uncompiled`、`stale`、`error` 的块 |
 | 重编译 `<id>` | 只处理这一块，不管状态 |
 | 粘贴了 `garden ui check` 的修复提示词 | 提示词里列出的块 |
 | 这篇哪里适合交互 | 只读建议模式，见文末，不改稿 |
@@ -30,7 +34,7 @@ description: >-
    npx garden ui scan content/posts/路径.md
    ```
 
-   stdout 是 JSON。每块有 `lang`、`id`、`status`、`startLine`、`hash`（整段围栏的哈希，写回时当 `--base`）、`intentHash`（原话的哈希）、`intent`（原话）、`caption`、`section`（所在小节标题）和 `diagnostics`。不要自己用正则找围栏。
+   stdout 是 JSON。`lang` 是 `garden-idea`（想法）、`garden-interactive`，或旧写法的 `intent` / `ui`。每块有 `lang`、`id`、`status`、`startLine`、`hash`（整段围栏的哈希，写回时当 `--base`）、`intentHash`（原话的哈希）、`intent`（原话）、`caption`、`section`（所在小节标题）和 `diagnostics`。不要自己用正则找围栏。
 
 2. 读规则：
 
@@ -42,11 +46,14 @@ description: >-
 
 3. 每块读原话和所在小节，三选一：
    - **写回正文**：一句话、一张表或一张 Mermaid 就能说清时。
-   - **写 `ui`**：读者需要拖、点、翻才能看懂时。
+   - **写 `garden interactive`**：读者需要拖、点、翻才能看懂时。
+   - **写一段 `diff`**：想法紧跟在一段完整代码后面，说的是「和上一版比改了什么」时。按原话写出 diff，用一段普通 Markdown 写回（只有这一个 `diff` 围栏）。写回后它紧挨着那段代码，页面会合成「代码 / 对比上一版」切换；diff 里的新行要和上面的完整代码一致。
+   - **写别的 `garden` 组件**：一张资源卡、几个指标、两种做法并排、一条时间线、一张静态图表、一张结构图、一份下载文件。
    - **写 `garden html`**：目录表达不了的画布动画、音频、物理模拟等。按 [garden-interactive-chart](../garden-interactive-chart/SKILL.md) 在同名目录写 HTML，用 `title` 写下判断。
 
-4. 写 `ui` 时：
-   - 原话原样放进块头的 `intent`，一个字都不改。`compiled` 不用写，`apply` 会写。
+4. 写 `garden interactive` 时：
+   - 格式：围栏头写 `garden interactive #<id>`；`---` 上面是 `caption`、`intent`、可选的 `expect`；`---` 下面是 `npx garden ui prompt` 里的组件树。
+   - 原话原样放进 `intent`，一个字都不改。
    - `caption` 摘原话里的判断。原话没有判断句，就根据小节内容补一句，并在回复里说明。
    - 原话里有已知点（"batch 1 时是 512 MiB"），写进 `expect`。
    - 数据写在块里。原话提到同名目录里已有的数据文件时，才用 `Data` 引用。
@@ -56,9 +63,7 @@ description: >-
 
    ````bash
    npx garden ui apply content/posts/路径.md --id <id> --base <hash> <<'GARDEN_UI'
-   ```ui
-   ---
-   id: ...
+   ```garden interactive #id
    caption: ...
    intent: |
      ...
@@ -68,8 +73,9 @@ description: >-
    GARDEN_UI
    ````
 
-   - 没写 id 的 `intent` 块用 `--intent-hash <intentHash>` 定位；原话重复时改用 `--at <startLine>`。
-   - 新内容可以是一个 `ui` 围栏、一个 `garden html` 围栏，或一段普通 Markdown（写回正文时）。
+   - 想法块没有 id，用 `--intent-hash <intentHash>` 定位；原话重复时改用 `--at <startLine>`。
+   - 新内容可以是一个 `garden` 组件围栏（interactive、card、stat……），或一段普通 Markdown（写回正文时）。旧稿里的 `ui` 块也可以按原格式写回。
+   - 新内容里不能再有没编译的想法。
    - 成功时 stdout 是 `{"ok":true,...}`。失败时 stderr 是 JSON，按 `code` 处理：
      - `apply-invalid`：新内容没通过校验，按 `diagnostics` 改了再写。
      - `apply-base`：块在扫描之后被改过。重新 `scan`，用新的 `hash`。
@@ -79,22 +85,23 @@ description: >-
 6. 全部写完后：
 
    ```bash
+   npx garden ui check content/posts/路径.md
    npx garden check content/posts/路径.md
    ```
 
-   直到 `ok` 为 true。同一块连续三次修不好，停下来，把诊断原样报告给用户。
+   前一条是提交前钩子跑的检查，要通过；后一条的 `ok` 要为 true。同一块连续三次修不好，停下来，把诊断原样报告给用户。
 
 7. 回复一张表：
 
    | id | 选择 | 配方 | 假设 | expect |
    | --- | --- | --- | --- | --- |
-   | kv-memory | ui | 参数台 | 默认序列取 4K | batch 1 时 512 MiB |
+   | kv-memory | garden interactive | 参数台 | 默认序列取 4K | batch 1 时 512 MiB |
 
    "假设"写原话没说、你替作者定下的东西（默认值、范围、补的 caption）。没有就写"无"。
 
 ## 禁止
 
-- 直接编辑稿件文件。稿件只经 `apply` 改动；`widget` 的 HTML 文件可以直接创建。
+- 直接编辑稿件文件。稿件只经 `apply` 改动；`garden html` 引用的 HTML 文件可以直接创建。
 - 编造原话里没有的数字。需要数字但原话没给时，用原话里的公式算，或者问作者。
 - 使用远程地址（图片、脚本、数据）。
 - 改动目标块之外的正文。
@@ -108,4 +115,4 @@ description: >-
 - 两种做法的差别（对比）
 - 一组格子、字节或内存布局（格子图）
 
-每处给出：所在小节、为什么文字不够、一段可以直接粘贴到该段落后面的 `intent` 草稿。草稿只写读者要做什么、看到什么，以及原文里已有的数字，不写组件名。最多 5 处；没有合适的就说没有。
+每处给出：所在小节、为什么文字不够、一段可以直接粘贴到该段落后面的 `garden` 想法块草稿。草稿只写读者要做什么、看到什么，以及原文里已有的数字，不写组件名。最多 5 处；没有合适的就说没有。

package/README.en.md

@@ -0,0 +1,57 @@
+# Garden
+
+[中文](README.md)
+
+Garden is a Claude-inspired personal blog framework. You write posts, short thoughts, and multi-part columns in Markdown inside your own Git repository, and describe structured or interactive components in a single plain-language sentence.
+
+Your site repository keeps only `site.config.yaml` and `content/`. Rendering, static export, and verification come from the `hd-garden` package.
+
+## 1. Create a site
+
+Requires **Node.js `>= 22.13.0`**, **Git**, and **GNU Make**:
+
+```bash
+npx hd-garden init my-blog
+cd my-blog
+npm install
+make dev
+```
+
+The published npm package is `hd-garden`; once installed inside a site, you can run `npx garden` (do not run `npx garden init` directly, as `garden` on npm is an unrelated package). Running `make dev` for the first time creates `.env.local`, installs the three AI skills under `.agents/skills/`, installs the pre-commit check in `.git/hooks/pre-commit`, and starts the dev server at `http://localhost:3000` (with the built-in handbook at `http://localhost:3000/garden/en`).
+
+## 2. Describe components in plain language (humans and Agents share the same CLI)
+
+Where you want a component or interactive calculation, write an unnamed `garden` fence describing what the reader should adjust and see:
+
+````markdown
+```garden
+让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
+```
+````
+
+Ask your Agent to compile the post using the bundled `garden-ui` skill: it runs `npx garden ui scan` to locate uncompiled or broken blocks, reads the component catalog from `npx garden ui prompt`, generates a `garden interactive` block (or `card`, `stat`, `compare`, `timeline`, `chart`, `figure`, `html`, `file`, or a `diff` block right below a code snippet), and writes only that fence back via `npx garden ui apply`. If you run `git commit` before compiling, the pre-commit hook runs `npx --no-install garden ui check --staged --quiet`, stops the commit, and prints a ready-to-paste fix prompt for your AI.
+
+## 3. Common commands
+
+```bash
+make new SLUG=writing-pace TITLE="Writing Pace" # Create a draft post in content/posts/
+make dev                                        # Sync content and start the local server
+CONTENT_INCLUDE_DRAFTS=1 make dev               # Preview drafts and future publishAt posts
+make check                                      # Run garden sync and garden build
+make update MESSAGE="Add writing-pace post"     # Check, commit, and push to origin
+npx garden check content/posts/writing-pace.md  # Validate front matter, components, and assets
+npx garden ui check --staged                    # Check staged posts for uncompiled ideas or UI errors
+npx garden ui catalog                           # Generate an offline component gallery at .garden/ui-catalog.html
+```
+
+## 4. Handbook and reference docs
+
+Start `make dev` and open `/garden/en` (Chinese at `/garden`), or read the markdown sources directly:
+
+- **[Garden Handbook (English)](docs/handbook/en/index.md)** · **[Garden 使用说明（中文）](docs/handbook/index.md)**: [Quick Start](docs/handbook/en/start.md), [Writing with AI](docs/handbook/en/ai-writing.md), [Site & Column Configuration](docs/handbook/en/config.md), [Deploy to GitHub Pages](docs/handbook/en/deploy.md), [Writing Posts & Thoughts](docs/handbook/en/writing.md), [How Reading Layout Works](docs/handbook/en/design.md), [9 Built-in Components](docs/handbook/en/components.md), and [Checking & Shortcuts](docs/handbook/en/workflow.md).
+- **[Quick Start Guide](docs/quick-start.md)** and **[GitHub Pages Deployment](docs/github-pages.md)**: single public repository or private source + public output repository setup, plus Giscus comments.
+- **[Admin Service](docs/admin-service.md)**: optional `/admin` server (local, Docker, or Cloudflare Workers) for posting thoughts from the web, uploading media to Alibaba Cloud OSS, and using the `/admin/ui` workbench.
+
+## License
+
+[MIT](LICENSE). Sites built with Garden should keep the Garden attribution link in the footer.

package/README.md

@@ -1,73 +1,58 @@
 # Garden
 
-用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。
+[English](README.en.md)
 
-站点仓库只保存稿件和身份：`content/` 与 `site.config.yaml`。页面、构建和发布工作流来自这个 Garden 包。
+Garden 是一个 Claude 风格的个人博客框架：文章、随想和专栏用 Markdown 写，保存在自己的 Git 仓库里；图表、指标和交互组件用一句自然语言描述就行。
 
-## 新建站点
+站点仓库只保存你的配置文件（`site.config.yaml`）与稿件（`content/`），页面渲染、静态构建和检查工具由 `hd-garden` 包提供。
+
+## 1. 新建站点
+
+需要 **Node.js `>= 22.13.0`**、**Git** 与 **GNU Make**：
 
 ```bash
 npx hd-garden init my-blog
 cd my-blog
 npm install
+make dev
 ```
 
-推荐把 GitHub 仓库命名为 `<你的 GitHub 用户名>.github.io`，并在 **Settings → Pages** 把 Source 设为 **GitHub Actions**。然后修改 `site.config.yaml`，再写第一篇 Markdown。公开包名是 `hd-garden`；装进站点之后也可以用 `garden`。不要运行 `npx garden init`，npm 上的 `garden` 是别人的样式库。
+公开包名是 `hd-garden`，装进站点后可使用 `npx garden`（不要直接运行未安装的 `npx garden init`，npm 上的 `garden` 是另一个包）。首次运行 `make dev` 会生成 `.env.local`、补齐 `.agents/skills/` 下的三个 AI skill，并在 `.git/hooks/pre-commit` 安装提交前检查，默认预览地址是 `http://localhost:3000`（使用说明在 `http://localhost:3000/garden`）。
 
-在国内想用 npm 镜像（例如 npmmirror），把 `registry` 写在自己的 `~/.npmrc` 或不提交的项目 `.npmrc` 里，不要让镜像地址进 `package-lock.json`：GitHub Actions 连不上镜像时 `npm ci` 会一直卡住。镜像会把新装包的 `resolved` 写成镜像地址，提交前运行 `node node_modules/hd-garden/scripts/check-lockfile-registry.mjs` 检查（Garden 仓库的 CI 也会检查）；报错时把这些地址的域名换回 `https://registry.npmjs.org/`，路径和 integrity 都不用改。
+如果在本地使用了 npm 镜像，请把 `registry` 留在 `~/.npmrc`，不要让镜像域名写进 `package-lock.json`（提交前可运行 `node node_modules/hd-garden/scripts/check-lockfile-registry.mjs` 检查）。
 
-也可以继续用 **Use this template**；该仓库同时是可运行的演示站。
+## 2. 用一句话写组件（人和 Agent 用同一套工具）
 
-完成后运行：
+在正文想放组件的位置写一个不带名字的 `garden` 围栏，只描述想让读者做什么、看到什么：
 
-```bash
-make update
+````markdown
+```garden
+让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
 ```
+````
 
-它会把本次改动提交并推送到源码仓库；发布工作流完成后，站点自动更新。初次使用请跟着[从零开始](docs/quick-start.md)做一遍。
-
-## 日常写作只需要知道这些
-
-| 你想做什么 | 从哪里开始 |
-| --- | --- |
-| 写一篇博文 | [新建文章](docs/content-authoring.md#新建一篇博文) |
-| 添加封面、图片、代码或公式 | [丰富文章内容](docs/content-authoring.md#丰富文章内容) |
-| 保存为草稿或置顶文章 | [草稿与置顶](docs/content-authoring.md#草稿与置顶) |
-| 建一个主题专栏 | [创建专栏](docs/content-authoring.md#创建专栏) |
-| 发布一条带多媒体的随想 | [发布随想](docs/content-authoring.md#发布随想) |
-| 改网站名称、作者和一级页标题 | [站点配置](docs/site-configuration.md) |
-| 给 AI 装可交互图表 skill | 第一次 `npx garden dev` 会自动装；更新用 `npx garden skill` |
-| 升级 Garden 引擎 | 把 `hd-garden` 改到新版本，再 `npm install` |
-| 发布本次改动 | `make update` |
+让 Agent 按站点里的 `garden-ui` skill 处理这篇稿件：Agent 先用 `npx garden ui scan` 读取待编译块的哈希，再读 `npx garden ui prompt` 的组件规则，生成 `garden interactive`（或 `card`、`stat`、`compare`、`timeline`、`chart`、`figure`、`html`、`file` 等内置组件，或在完整代码下方生成 `diff`），最后用 `npx garden ui apply` 只替换该围栏。如果你在编译前直接 `git commit`，pre-commit 钩子会运行同一条 `npx --no-install garden ui check --staged --quiet` 拦下提交，并打印一段可直接粘贴给 AI 的修复提示词。
 
-## 常用命令
+## 3. 常用命令
 
 ```bash
-make new       # 创建文章草稿（无需安装 npm 依赖）
-make skill     # 安装可交互图表 skill
-make dev       # 首次准备并本地预览
-make check     # 检查内容与运行测试
-make build     # 构建公开站点
-make update    # 检查、提交并触发自动发布
+make new SLUG=writing-pace TITLE="慢慢写"      # 在 content/posts/ 下创建文章草稿
+make dev                                       # 同步内容并启动本地预览
+CONTENT_INCLUDE_DRAFTS=1 make dev              # 连同草稿和未来定时文章一起预览
+make check                                     # 运行 garden sync 与 garden build 验证全站
+make update MESSAGE="新增一篇文章"             # 检查通过后提交并推送到远端仓库
+npx garden check content/posts/writing-pace.md # 单独检查一篇文章的标题、组件与资源路径
+npx garden ui check --staged                   # 检查暂存区稿件中的想法块与交互组件
+npx garden ui catalog                          # 在 .garden/ui-catalog.html 生成离线组件清单
 ```
 
-需要自定义提交说明时：
-
-```bash
-make update MESSAGE="新增一篇文章"
-```
-
-`make dev` 会在首次运行时自动安装依赖并创建 `.env.local`，同时说明如何接上评论。线上发布要求 Actions Variables 里有 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`；留空会让构建失败。确定不开放评论时设置 `GISCUS_DISABLED=1`。`make update` 会先检查，再提交并推送工作区中的所有改动。不想发布的文件请先移出仓库或加入 `.gitignore`。
-
-## 进一步配置
+## 4. 使用说明与深入文档
 
-评论接法见[从零开始](docs/quick-start.md)。跑通以后，再按需查看：
+本地运行 `make dev` 后访问 `/garden`（英文版在 `/garden/en`），或直接阅读仓库内的文档：
 
-- [评论、Webmentions 与内容分发](docs/integrations.md)
-- [随想管理后台](docs/admin-service.md)
-- [GitHub Pages 与自定义域名](docs/github-pages.md)
-- [系统怎么工作](docs/architecture.md)
-- [全部文档](docs/README.md)
+- **[Garden 使用说明（中文）](docs/handbook/index.md)** · **[Garden Handbook (English)](docs/handbook/en/index.md)**：快速开始、[用 AI 写作](docs/handbook/ai-writing.md)、[站点与专栏配置](docs/handbook/config.md)、[发布到 GitHub Pages](docs/handbook/deploy.md)、[写文章与随想](docs/handbook/writing.md)、[阅读排版](docs/handbook/design.md)、[9 个内置组件](docs/handbook/components.md) 与 [语法检查](docs/handbook/workflow.md)。
+- **[从零开始](docs/quick-start.md)** 与 **[GitHub Pages 部署](docs/github-pages.md)**：单公开仓库或「私有源码仓库 + 公开页面仓库」的 Actions 配置与 Giscus 评论接入。
+- **[独立管理后台](docs/admin-service.md)**：可选的 `/admin` 服务（本地、Docker 或 Cloudflare Workers），支持网页发随想、阿里云 OSS 媒体直传与 `/admin/ui` 组件工作台。
 
 ## 许可证
 

package/app/admin/preview/[...path]/page.tsx

@@ -88,7 +88,7 @@ export default async function DraftPreviewPage({ params }: { params: Promise<{ p
         <h1 className="ui-admin-preview-title">{typeof data.title === "string" ? data.title : post}</h1>
         {typeof data.description === "string" ? <p className="ui-studio-meta">{data.description}</p> : null}
         <article className="article-body">
-          <MarkdownArticle content={proxyAssets(content, post)} />
+          <MarkdownArticle content={proxyAssets(content, post)} numbering={data.numbering === false ? false : undefined} />
         </article>
       </section>
     </AdminUiShell>

package/app/blog/[...path]/page.tsx

@@ -19,6 +19,8 @@ import { TableOfContents } from "../../components/TableOfContents";
 import { Comments } from "../../components/Comments";
 import { Webmentions } from "../../components/Webmentions";
 import { ArticleTags } from "../../components/ArticleTags";
+import { ArticlePager } from "../../components/ArticlePager";
+import { adjacentByDate } from "../../../ui/garden/adjacent.mjs";
 import {
   absoluteUrl,
   getSiteUrl,
@@ -26,6 +28,7 @@ import {
 } from "../../lib/site";
 import { githubUrl, siteConfig } from "../../site.config";
 import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../ui/garden/static-params.mjs";
+import { ui } from "../../lib/i18n";
 
 export function generateStaticParams() {
   return staticParams(posts.map((post) => ({ path: post.path.split("/") })), { path: [STATIC_PLACEHOLDER] });
@@ -77,11 +80,12 @@ export default async function PostPage({
     if (isStaticPlaceholder(path)) return null;
     notFound();
   }
-  const headings = extractHeadings(post.content);
+  const headings = extractHeadings(post.content, { numbering: post.numbering });
   const baseUrl = await getSiteUrl();
   const pathname = postHref(post);
   const canonicalUrl = absoluteUrl(pathname, baseUrl);
   const wordCount = estimateWordCount(post.content);
+  const { prev, next } = adjacentByDate(posts, (item: { path: string }) => item.path === post.path);
 
   return (
     <main className="reading-page post-reading-page">
@@ -106,7 +110,7 @@ export default async function PostPage({
               </time>
             </li>
             {post.updated ? <li>更新于 {formatDate(post.updated)}</li> : null}
-            <li>约 {wordCount.toLocaleString("en-US")} 字</li>
+            <li>{ui().wordCount(wordCount)}</li>
             {originalUrl(post) ? (
               <li>
                 <a className="orig ext" href={originalUrl(post)} target="_blank" rel="noopener noreferrer">原文 ↗</a>
@@ -125,13 +129,17 @@ export default async function PostPage({
             <ArticleMeasure />
             <div className="e-content">
               {post.description ? <p className="lead quote-plain p-summary">{post.description}</p> : null}
-              <MarkdownArticle content={post.content} />
+              <MarkdownArticle content={post.content} numbering={post.numbering} />
             </div>
             <ArticleReferences references={post.references} />
             <Webmentions
               target={canonicalUrl}
               endpoint={webmentionApiEndpoint()}
             />
+            <ArticlePager
+              prev={prev ? { href: postHref(prev), title: prev.title } : null}
+              next={next ? { href: postHref(next), title: next.title } : null}
+            />
             <Comments slug={post.path} />
           </div>
           <TableOfContents headings={headings} />

package/app/columns/[column]/[...path]/page.tsx

@@ -1,9 +1,10 @@
 import Link from "next/link";
+import { ArticlePager } from "../../../components/ArticlePager";
 import { CoverImage } from "../../../components/CoverImage";
 import type { Metadata } from "next";
 import { FEED_ALTERNATES } from "../../../lib/page-alternates";
 import { notFound } from "next/navigation";
-import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
+import { ArrowLeft } from "@phosphor-icons/react/ssr";
 import {
   columns,
   extractHeadings,
@@ -28,6 +29,7 @@ import {
 import { githubUrl, siteConfig } from "../../../site.config";
 import { siteHref } from "../../../lib/site-href";
 import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../../ui/garden/static-params.mjs";
+import { ui } from "../../../lib/i18n";
 
 export function generateStaticParams() {
   return staticParams(
@@ -88,8 +90,9 @@ export default async function ColumnEntryPage({
   const series = columns.filter((item) => item.column === column);
   const listed = [...series].sort((left, right) => Date.parse(right.date) - Date.parse(left.date));
   const currentIndex = series.findIndex((item) => item.path === entry.path);
-  const next = series[currentIndex + 1];
-  const headings = extractHeadings(entry.content);
+  const prev = series[currentIndex - 1] ?? null;
+  const next = series[currentIndex + 1] ?? null;
+  const headings = extractHeadings(entry.content, { numbering: entry.numbering });
   const baseUrl = await getSiteUrl();
   const pathname = columnHref(entry);
   const canonicalUrl = absoluteUrl(pathname, baseUrl);
@@ -147,23 +150,18 @@ export default async function ColumnEntryPage({
         <ArticleMeasure />
         <div className="e-content">
           {entry.description ? <p className="lead p-summary">{entry.description}</p> : null}
-          <MarkdownArticle content={entry.content} />
+          <MarkdownArticle content={entry.content} numbering={entry.numbering} />
         </div>
         <ArticleReferences references={entry.references} />
-        {next && (
-          <Link
-            href={columnHref(next)}
-            className="next-entry"
-          >
-            <span>下一篇</span>
-            <strong>{next.title}</strong>
-            <ArrowRight size={20} />
-          </Link>
-        )}
         <Webmentions
           target={canonicalUrl}
           endpoint={webmentionApiEndpoint()}
         />
+        <ArticlePager
+          label={ui().columnPagerLabel}
+          prev={prev ? { href: columnHref(prev), title: prev.title } : null}
+          next={next ? { href: columnHref(next), title: next.title } : null}
+        />
         <Comments slug={`${column}:${entry.path}`} />
       </article>
 

package/app/components/ArticleMeasure.tsx

@@ -45,7 +45,14 @@ export function ArticleMeasure() {
       return width;
     };
 
+    const docPage = article.closest<HTMLElement>(".garden-doc-page");
+
     const placeToc = () => {
+      if (docPage) {
+        root.removeAttribute("data-toc-yield");
+        root.removeAttribute("data-toc-hide");
+        return;
+      }
       if (!toc) {
         root.removeAttribute("data-toc-yield");
         return;
@@ -74,10 +81,38 @@ export function ArticleMeasure() {
       }
     };
 
+    const clampMargin = (margin: { left: number; right: number }, maxRoom: number | null) => {
+      if (maxRoom === null) return margin;
+      const side = Math.max(0, Math.min(margin.left, maxRoom));
+      return { left: side, right: side };
+    };
+
     const measure = (refresh: boolean) => {
       // Measure the text column, not the whole article grid (which includes the TOC rail).
       const articleBox = (article.querySelector(".markdown-body") ?? article).getBoundingClientRect();
       const viewport = root.clientWidth;
+      let docMaxRoom: number | null = null;
+      if (docPage) {
+        const sidebar = docPage.querySelector<HTMLElement>(".gdoc-sidebar");
+        let leftLimit = 24;
+        if (sidebar && getComputedStyle(sidebar).position === "sticky") {
+          const sbBox = sidebar.getBoundingClientRect();
+          if (sbBox.width > 0 && sbBox.right <= articleBox.left + 1) {
+            leftLimit = sbBox.right + 16;
+          }
+        }
+        let rightLimit = viewport - 24;
+        if (toc && getComputedStyle(toc).display !== "none") {
+          const tocBox = toc.getBoundingClientRect();
+          if (tocBox.width > 0 && tocBox.left >= articleBox.right - 1) {
+            rightLimit = tocBox.left - translatedX(toc) - 16;
+          }
+        }
+        docMaxRoom = Math.max(
+          0,
+          Math.floor(Math.min(articleBox.left - leftLimit, rightLimit - articleBox.right)),
+        );
+      }
       const widen = (element: HTMLElement, margin: { left: number; right: number }) => {
         if (margin.left <= 0) return;
         element.style.setProperty("--wl", `${margin.left}px`);
@@ -89,13 +124,13 @@ export function ArticleMeasure() {
         const width = tableWidth(wrap, refresh);
         resetWide(wrap);
         if (!width) return;
-        widen(wrap, tableBreakout({
+        widen(wrap, clampMargin(tableBreakout({
           viewport,
           articleLeft: articleBox.left,
           articleRight: articleBox.right,
           tableClient: wrap.clientWidth,
           tableScroll: width,
-        }));
+        }), docMaxRoom));
       });
       // Images: as wide as they display (2x screenshots at half their pixels), up to 1040px in total.
       article.querySelectorAll<HTMLElement>(".fig").forEach((figure) => {
@@ -115,7 +150,7 @@ export function ArticleMeasure() {
         if (!pixels) return;
         // width="" written by the build is the pixel size, not an author's choice.
         const attrWidth = known ? Number(image.dataset.aw) || 0 : Number(image.getAttribute("width")) || 0;
-        const breakout = figureBreakout({
+        const breakout = clampMargin(figureBreakout({
           viewport,
           articleLeft: articleBox.left,
           articleRight: articleBox.right,
@@ -123,7 +158,7 @@ export function ArticleMeasure() {
           imageClient: image.clientWidth,
           naturalWidth: pixels,
           attrWidth,
-        });
+        }), docMaxRoom);
         widen(figure, breakout);
         // Only a widened image, or one with a width attribute, gets an inline width.
         const width = figureImageWidth({ naturalWidth: pixels, attrWidth, widened: breakout.left > 0 });

package/app/components/ArticlePager.tsx

@@ -0,0 +1,32 @@
+import Link from "next/link";
+import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
+import { ui } from "../lib/i18n";
+
+export type PagerTarget = { href: string; title: string } | null;
+
+/** 上一篇 / 下一篇, the same cards as the handbook pager. A missing side stays empty. */
+export function ArticlePager({ prev, next, label = ui().pagerLabel }: { prev: PagerTarget; next: PagerTarget; label?: string }) {
+  if (!prev && !next) return null;
+  return (
+    <nav className="gdoc-pager article-pager" aria-label={label}>
+      {prev ? (
+        <Link href={prev.href} className="gdoc-pager-card is-prev">
+          <span className="gdoc-pager-dir">
+            <ArrowLeft size={14} aria-hidden="true" />
+            {ui().prev}
+          </span>
+          <strong>{prev.title}</strong>
+        </Link>
+      ) : null}
+      {next ? (
+        <Link href={next.href} className="gdoc-pager-card is-next">
+          <span className="gdoc-pager-dir">
+            {ui().next}
+            <ArrowRight size={14} aria-hidden="true" />
+          </span>
+          <strong>{next.title}</strong>
+        </Link>
+      ) : null}
+    </nav>
+  );
+}

package/app/components/Comments.tsx

@@ -1,6 +1,7 @@
 import { ChatCircle, GithubLogo } from "@phosphor-icons/react/ssr";
 import { readGiscusConfig } from "../lib/giscus-config";
 import { GiscusComments } from "./GiscusComments";
+import { ui } from "../lib/i18n";
 
 export function Comments({ slug }: { slug: string }) {
   const config = readGiscusConfig();
@@ -10,7 +11,7 @@ export function Comments({ slug }: { slug: string }) {
       <div className="comments-heading">
         <ChatCircle size={23} />
         <div>
-          <h2 id={`comments-heading-${slug}`}>评论</h2>
+          <h2 id={`comments-heading-${slug}`}>{ui().comments}</h2>
           <p>
             {config
               ? "评论由 GitHub Discussions 保存和管理。"

package/app/components/FeedMore.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+type Labels = { nextPage: string; loadingMore: string; loadFailed: string; feedEnd: string };
+
+/**
+ * The end of a feed page. Without JavaScript it is a plain 下一页 link to the
+ * next pre-rendered page. With JavaScript, when it scrolls near the viewport it
+ * fetches that page's HTML, appends its items to the list above and moves on.
+ */
+export function FeedMore({ next, streamSelector, labels }: { next: string | null; streamSelector: string; labels: Labels }) {
+  // Page links are written without the basePath; the pages fetched later carry it already.
+  const base = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/u, "");
+  const [href, setHref] = useState(next ? `${base}${next}` : null);
+  const [state, setState] = useState<"idle" | "loading" | "error">("idle");
+  const navRef = useRef<HTMLElement>(null);
+  const busy = useRef(false);
+
+  const load = useCallback(async () => {
+    if (!href || busy.current) return;
+    busy.current = true;
+    setState("loading");
+    try {
+      const response = await fetch(href, { headers: { Accept: "text/html" } });
+      if (!response.ok) throw new Error(String(response.status));
+      const page = new DOMParser().parseFromString(await response.text(), "text/html");
+      const incoming = page.querySelector(streamSelector);
+      const stream = navRef.current?.parentElement?.querySelector(streamSelector);
+      if (!incoming || !stream) throw new Error("feed markup");
+      stream.append(...Array.from(incoming.children).map((node) => document.importNode(node, true)));
+      setHref(page.querySelector<HTMLAnchorElement>("[data-feed-next]")?.getAttribute("href") ?? null);
+      setState("idle");
+    } catch {
+      setState("error");
+    } finally {
+      busy.current = false;
+    }
+  }, [href, streamSelector]);
+
+  useEffect(() => {
+    const node = navRef.current;
+    if (!node || !href || state !== "idle" || typeof IntersectionObserver === "undefined") return;
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) void load();
+    }, { rootMargin: "600px 0px" });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [href, state, load]);
+
+  return (
+    <nav ref={navRef} className="feed-more" aria-live="polite">
+      {href ? (
+        <a
+          href={href}
+          rel="next"
+          data-feed-next=""
+          onClick={(event) => {
+            event.preventDefault();
+            void load();
+          }}
+        >
+          {state === "loading" ? labels.loadingMore : state === "error" ? labels.loadFailed : labels.nextPage}
+        </a>
+      ) : (
+        <span className="feed-end">{labels.feedEnd}</span>
+      )}
+    </nav>
+  );
+}