hd-garden 0.9.0 → 0.9.2

package/app/components/bookshelf/schema.mjs

@@ -0,0 +1,86 @@
+export class BookshelfConfigError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "BookshelfConfigError";
+    this.code = code;
+  }
+}
+
+const SIZES = new Set(["thin", "s-short", "s-mid", "s-tall"]);
+
+function record(value, code, message) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new BookshelfConfigError(code, message);
+  return value;
+}
+
+function optionalString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function parseFiller(value, where) {
+  if (value == null || value === false) return undefined;
+  if (value === true || value === "sand" || value === "cream") return value;
+  throw new BookshelfConfigError("filler", `${where} 的 filler 只能是 true、sand 或 cream。`);
+}
+
+function parseSize(value, where) {
+  if (value == null || value === "") return undefined;
+  if (typeof value === "string" && SIZES.has(value)) return value;
+  throw new BookshelfConfigError("size", `${where} 的 size 只能是 thin、s-short、s-mid 或 s-tall。`);
+}
+
+function parseBook(value, where, seen) {
+  const book = record(value, "book", `${where} 必须是映射。`);
+  const id = optionalString(book.id);
+  const title = optionalString(book.title);
+  if (!id || !title) throw new BookshelfConfigError("book", `${where} 需要 id 和 title。`);
+  if (seen.has(id)) throw new BookshelfConfigError("duplicate-id", `${where} 的 id「${id}」重复。`);
+  seen.add(id);
+  return {
+    id,
+    title,
+    author: optionalString(book.author),
+    spine: optionalString(book.spine),
+    size: parseSize(book.size, where),
+    cover: optionalString(book.cover),
+    color: optionalString(book.color),
+    filler: parseFiller(book.filler, where),
+    post: optionalString(book.post),
+    note: typeof book.note === "string" && book.note.trim() ? book.note.trim() : undefined,
+  };
+}
+
+function parseShelf(value, index, seen) {
+  const where = `shelves[${index}]`;
+  const shelf = record(value, "shelf", `${where} 必须是映射。`);
+  const id = optionalString(shelf.id);
+  const name = optionalString(shelf.name);
+  if (!id || !name) throw new BookshelfConfigError("shelf", `${where} 需要 id 和 name。`);
+  if (!Array.isArray(shelf.books) || shelf.books.length === 0) {
+    throw new BookshelfConfigError("shelf", `${where} 的 books 必须是非空数组。`);
+  }
+  return {
+    id,
+    name,
+    books: shelf.books.map((book, bookIndex) => parseBook(book, `${where}.books[${bookIndex}]`, seen)),
+  };
+}
+
+/** Validate `content/bookshelf.yaml`. Throws `BookshelfConfigError` with a stable `code`. */
+export function parseBookshelfConfig(input) {
+  const data = record(input, "invalid-root", "content/bookshelf.yaml 必须是映射。");
+  const title = optionalString(data.title);
+  if (!title) throw new BookshelfConfigError("missing-title", "content/bookshelf.yaml 缺少 title。");
+  if (!Array.isArray(data.shelves) || data.shelves.length === 0) {
+    throw new BookshelfConfigError("shelves", "content/bookshelf.yaml 的 shelves 必须是非空数组。");
+  }
+  const seen = new Set();
+  return {
+    title,
+    description: optionalString(data.description),
+    eyebrow: optionalString(data.eyebrow),
+    shelves: data.shelves.map((shelf, index) => parseShelf(shelf, index, seen)),
+  };
+}

package/app/components/bookshelf/schema.ts

@@ -1,4 +1,5 @@
 import type { BookshelfFiller, BookshelfSize } from "./model";
+import { BookshelfConfigError as ConfigError, parseBookshelfConfig as parseConfig } from "./schema.mjs";
 
 export type BookshelfConfigCode =
   | "invalid-root"
@@ -8,32 +9,43 @@ export type BookshelfConfigCode =
   | "book"
   | "duplicate-id"
   | "size"
-  | "filler";
+  | "filler"
+  | "cover"
+  | "post";
 
-export class BookshelfConfigError extends Error {
+export interface BookshelfConfigError extends Error {
   readonly code: BookshelfConfigCode;
-
-  constructor(code: BookshelfConfigCode, message: string) {
-    super(message);
-    this.name = "BookshelfConfigError";
-    this.code = code;
-  }
 }
 
+/** Runtime class lives in `schema.mjs` so node tests and the site build share one instance. */
+export const BookshelfConfigError = ConfigError as unknown as new (
+  code: BookshelfConfigCode,
+  message: string,
+) => BookshelfConfigError;
+
+/**
+ * One volume in `content/bookshelf.yaml`.
+ *
+ * Site contract (what a blog drops in to replace the package demo):
+ * - `post` is a path under `content/posts/`, without `.md`. The shelf renders that
+ *   post as the open-book note (front matter `description` is the short summary).
+ * - `cover` is either a full URL (`https://…`, `//…`, or a site path starting
+ *   with `/`) or a file name. A file name is published at `/media/covers/<file>`,
+ *   the same URL `content/covers/` gets when a post's `cover` names that file.
+ *   Omit `cover` to reuse the post's own cover.
+ * - `color` (`#rgb` or `#rrggbb`) is the spine cloth and the open-page palette.
+ * - `note` is Markdown used only when `post` is absent.
+ */
 export type BookshelfFileBook = {
   id: string;
   title: string;
   author?: string;
   spine?: string;
   size?: BookshelfSize;
-  /** Douban or same-site cover URL. Absent → text placeholder. */
   cover?: string;
-  /** Spine and cloth color. Sample this from the cover when you have one. */
   color?: string;
   filler?: BookshelfFiller;
-  /** Path under content/posts, without `.md`. */
   post?: string;
-  /** Markdown note used when `post` is absent. */
   note?: string;
 };
 
@@ -50,81 +62,7 @@ export type BookshelfFile = {
   shelves: BookshelfFileShelf[];
 };
 
-const SIZES = new Set<BookshelfSize>(["thin", "s-short", "s-mid", "s-tall"]);
-
-function record(value: unknown, code: BookshelfConfigCode, message: string): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new BookshelfConfigError(code, message);
-  return value as Record<string, unknown>;
-}
-
-function optionalString(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed ? trimmed : undefined;
-}
-
-function parseFiller(value: unknown, where: string): BookshelfFiller | undefined {
-  if (value == null || value === false) return undefined;
-  if (value === true || value === "sand" || value === "cream") return value;
-  throw new BookshelfConfigError("filler", `${where} 的 filler 只能是 true、sand 或 cream。`);
-}
-
-function parseSize(value: unknown, where: string): BookshelfSize | undefined {
-  if (value == null || value === "") return undefined;
-  if (typeof value === "string" && SIZES.has(value as BookshelfSize)) return value as BookshelfSize;
-  throw new BookshelfConfigError("size", `${where} 的 size 只能是 thin、s-short、s-mid 或 s-tall。`);
-}
-
-function parseBook(value: unknown, where: string, seen: Set<string>): BookshelfFileBook {
-  const book = record(value, "book", `${where} 必须是映射。`);
-  const id = optionalString(book.id);
-  const title = optionalString(book.title);
-  if (!id || !title) throw new BookshelfConfigError("book", `${where} 需要 id 和 title。`);
-  if (seen.has(id)) throw new BookshelfConfigError("duplicate-id", `${where} 的 id「${id}」重复。`);
-  seen.add(id);
-  return {
-    id,
-    title,
-    author: optionalString(book.author),
-    spine: optionalString(book.spine),
-    size: parseSize(book.size, where),
-    cover: optionalString(book.cover),
-    color: optionalString(book.color),
-    filler: parseFiller(book.filler, where),
-    post: optionalString(book.post),
-    note: typeof book.note === "string" && book.note.trim() ? book.note.trim() : undefined,
-  };
-}
-
-function parseShelf(value: unknown, index: number, seen: Set<string>): BookshelfFileShelf {
-  const where = `shelves[${index}]`;
-  const shelf = record(value, "shelf", `${where} 必须是映射。`);
-  const id = optionalString(shelf.id);
-  const name = optionalString(shelf.name);
-  if (!id || !name) throw new BookshelfConfigError("shelf", `${where} 需要 id 和 name。`);
-  if (!Array.isArray(shelf.books) || shelf.books.length === 0) {
-    throw new BookshelfConfigError("shelf", `${where} 的 books 必须是非空数组。`);
-  }
-  return {
-    id,
-    name,
-    books: shelf.books.map((book, bookIndex) => parseBook(book, `${where}.books[${bookIndex}]`, seen)),
-  };
-}
-
 /** Validate `content/bookshelf.yaml`. Throws `BookshelfConfigError` with a stable `code`. */
 export function parseBookshelfConfig(input: unknown): BookshelfFile {
-  const data = record(input, "invalid-root", "content/bookshelf.yaml 必须是映射。");
-  const title = optionalString(data.title);
-  if (!title) throw new BookshelfConfigError("missing-title", "content/bookshelf.yaml 缺少 title。");
-  if (!Array.isArray(data.shelves) || data.shelves.length === 0) {
-    throw new BookshelfConfigError("shelves", "content/bookshelf.yaml 的 shelves 必须是非空数组。");
-  }
-  const seen = new Set<string>();
-  return {
-    title,
-    description: optionalString(data.description),
-    eyebrow: optionalString(data.eyebrow),
-    shelves: data.shelves.map((shelf, index) => parseShelf(shelf, index, seen)),
-  };
+  return parseConfig(input) as BookshelfFile;
 }

package/app/components/bookshelf/types.ts

@@ -4,9 +4,10 @@ export type { BookshelfFiller, BookshelfSize };
 
 /**
  * One volume on the shelf.
- * `cover: true` uses the approved jacket at `/covers/<id>.jpg`.
- * A string is a cover URL (Douban). Falsy covers are text spines and are omitted in state A.
- * `color` is the spine cloth. It should be sampled from the cover.
+ * `cover: true` uses the package-demo jacket at `/covers/<id>.jpg`.
+ * A string is a cover URL (`/media/covers/…` for a site shelf, or any absolute URL).
+ * Falsy covers are text spines and are omitted in state A.
+ * `color` is the spine cloth and the open-page palette. Sample it from the cover.
  */
 export type BookshelfBook = {
   id: string;
@@ -19,6 +20,10 @@ export type BookshelfBook = {
   filler?: BookshelfFiller;
   /** Key into the notes map. Null means the demo placeholder paragraph. */
   note?: string | null;
+  /** `content/posts` path without `.md`, when the note is a post. */
+  post?: string;
+  /** Full-note address, shaped for this build. Set when `post` is set. */
+  href?: string;
 };
 
 export type BookshelfShelf = {
@@ -30,9 +35,21 @@ export type BookshelfShelf = {
 export type BookshelfNote = {
   title: string;
   body: string;
+  /** The post's front matter description. The open book's right page. */
+  summary?: string;
 };
 
 export type BookshelfProps = {
+  /** Site shelf. Omit both `catalog` and `notes` for the package demo. */
   catalog?: BookshelfShelf[];
   notes?: Record<string, BookshelfNote>;
+  /** Heading on the shelf. Omit for the package-demo title. */
+  title?: string;
+  /** Small line above the heading. Omit for the package-demo brand. */
+  eyebrow?: string;
+  /**
+   * Site page: the shelf sits in the blog column. The package demo leaves this
+   * unset and keeps its own full-viewport frame.
+   */
+  embedded?: boolean;
 };

package/app/garden-modules.d.ts

@@ -103,3 +103,9 @@ declare module "@garden/site-config" {
   };
   export const githubUrl: string;
 }
+
+declare module "@garden/bookshelf" {
+  import type { BookshelfMount } from "./components/bookshelf/catalog";
+  /** Site shelf from content/bookshelf.yaml, or null when that file is absent. */
+  export const bookshelf: BookshelfMount | null;
+}

package/app/layout.tsx

@@ -4,6 +4,7 @@ import "./globals.css";
 import "./styles/tokens.css";
 import "./styles/a2.css";
 import "./styles/shell.css";
+import { bookshelf } from "@garden/bookshelf";
 import { SiteChrome } from "./components/SiteChrome";
 import {
   getSiteUrl,
@@ -94,7 +95,7 @@ export default function RootLayout({
         )}
       </head>
       <body>
-        <SiteChrome>{children}</SiteChrome>
+        <SiteChrome bookshelfSite={bookshelf != null}>{children}</SiteChrome>
       </body>
     </html>
   );

package/app/lib/i18n.ts

@@ -131,7 +131,7 @@ const zh = {
   fuzzy: "支持模糊匹配",
   escToClose: "关闭",
   noResults: (q: string) => (q ? `没有找到和「${q}」相关的文章` : "还没有可以搜索的内容"),
-  navLabels: { "/blog/": "文章", "/thoughts/": "随想", "/columns/": "专栏", "/tags/": "标签", "/about/": "关于" } as Record<string, string>,
+  navLabels: { "/blog/": "文章", "/thoughts/": "随想", "/columns/": "专栏", "/tags/": "标签", "/bookshelf/": "书架", "/about/": "关于" } as Record<string, string>,
   // Home page
   homeLatestBadge: "最新文章",
   homeRecentHeading: "最近更新",
@@ -414,7 +414,7 @@ const en: typeof zh = {
   fuzzy: "Fuzzy matching",
   escToClose: "to close",
   noResults: (q: string) => (q ? `No posts match “${q}”` : "Nothing to search yet"),
-  navLabels: { "/blog/": "Posts", "/thoughts/": "Thoughts", "/columns/": "Columns", "/tags/": "Tags", "/about/": "About" },
+  navLabels: { "/blog/": "Posts", "/thoughts/": "Thoughts", "/columns/": "Columns", "/tags/": "Tags", "/bookshelf/": "Shelf", "/about/": "About" },
   // Home page
   homeLatestBadge: "Latest post",
   homeRecentHeading: "Recent updates",

package/app/sitemap.ts

@@ -1,4 +1,5 @@
 import type { MetadataRoute } from "next";
+import { bookshelf } from "@garden/bookshelf";
 import { columnHref, columns, postHref, posts, thoughtHref } from "./lib/content";
 import { absoluteUrl, getSiteUrl } from "./lib/site";
 import { getPublishedThoughts } from "./lib/public-thoughts";
@@ -14,6 +15,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
     { path: "/columns", priority: 0.8, changeFrequency: "weekly" as const },
     { path: "/about", priority: 0.5, changeFrequency: "monthly" as const },
     { path: "/garden", priority: 0.4, changeFrequency: "monthly" as const },
+    // Only a real shelf is a page. The package demo stays out of the sitemap.
+    ...(bookshelf ? [{ path: "/bookshelf", priority: 0.6, changeFrequency: "weekly" as const }] : []),
   ].map((route) => ({
     url: absoluteUrl(siteHref(route.path), baseUrl),
     changeFrequency: route.changeFrequency,

package/docs/handbook/config.md

@@ -1,12 +1,12 @@
 ---
 title: 站点与专栏配置
 navTitle: 站点与专栏配置
-description: 配置 site.config.yaml 中的站点信息、各页标题、自定义品牌图标与 content/columns.yaml 专栏。
+description: 配置 site.config.yaml 中的站点信息、各页标题、自定义品牌图标、content/columns.yaml 专栏与 content/bookshelf.yaml 书架。
 section: getting-started
 order: 3
 ---
 
-站点的全局文字与外观信息集中在根目录的 `site.config.yaml`，专栏目录集中在 `content/columns.yaml`。修改后运行 `npx garden sync`（或直接 `make dev`）即可生效。
+站点的全局文字与外观信息集中在根目录的 `site.config.yaml`，专栏目录集中在 `content/columns.yaml`，读书笔记书架集中在 `content/bookshelf.yaml`。修改后运行 `npx garden sync`（或直接 `make dev`）即可生效。
 
 ## 1. `site.config.yaml` 完整结构
 
@@ -125,3 +125,42 @@ columns:
 | `status` | 否 | 状态标识：`default`（或不写，显示为「持续更新」）、`ongoing`（「连载中」）、`completed`（「已完结」）；旧写法 `持续更新`、`连载中`、`已完结` 仍可识别，其他文字按原样显示 |
 | `cover` | 否 | 专栏封面图路径（相对 `content/covers/`） |
 | `posts` | 是 | 按阅读顺序排列的文章路径列表（相对于 `content/posts/`，不带 `.md` 后缀） |
+
+## 3. 配置读书笔记书架（`content/bookshelf.yaml`）
+
+`/bookshelf` 在站点写了 `content/bookshelf.yaml` 时渲染这里的书，并带上站点顶栏，和其他页面一样可以被索引。没有这个文件时，`/bookshelf` 只在引擎包内的中文验收里显示内置 demo（无顶栏、不收录）；正式站要真书目，就放下这份文件。
+
+每本书的 `post` 是 `content/posts/` 下的路径，不带 `.md`。打开后的左页是书名，右页是这篇的摘要（front matter 的 `description`），笔记页是正文。封面写文件名时，地址是 `/media/covers/<文件名>`，和博文 front matter 的 `cover` 一致，文件放在 `content/covers/`。已经写了 `https://…`，或以 `/` 开头的地址，则原样使用。不写 `cover` 时，沿用这篇博文自己的封面。`color` 取封面的主色（`#rgb` 或 `#rrggbb`），用来画书脊和打开后的纸页。
+
+```yaml
+title: 读书笔记
+description: 读过的书，和留下的笔记。
+eyebrow: 花园
+shelves:
+  - id: recent
+    name: 最近在读
+    books:
+      - id: ddia
+        title: 数据密集型应用系统设计
+        author: Martin Kleppmann
+        cover: ddia.jpg
+        color: "#8b3a2f"
+        post: note/ddia
+```
+
+| 字段 | 必填 | 说明 |
+| :--- | :--- | :--- |
+| `title` | 是 | 书架页标题 |
+| `description` | 否 | 页面简介 |
+| `eyebrow` | 否 | 架面眉题。不写时用站点名 |
+| `shelves` | 是 | 非空数组。每一层要有 `id`、`name`，以及非空的 `books` |
+| `books[].id` | 是 | 整架唯一 |
+| `books[].title` | 是 | 书名，显示在左页和笔记页 |
+| `books[].author` | 否 | 作者 |
+| `books[].spine` | 否 | 书脊文字，默认同 `title` |
+| `books[].size` | 否 | `thin`、`s-short`、`s-mid`、`s-tall`。普通书默认 `s-mid`，占位薄册默认 `thin` |
+| `books[].cover` | 否 | 文件名，或完整 URL |
+| `books[].color` | 否 | 书脊和打开后的纸色 |
+| `books[].filler` | 否 | `true`、`sand` 或 `cream`，占位薄册，不能打开 |
+| `books[].post` | 否 | 笔记正文所在的博文 |
+| `books[].note` | 否 | 没有 `post` 时直接写的 Markdown 笔记 |

package/docs/handbook/en/config.md

@@ -1,12 +1,12 @@
 ---
 title: Site & Column Config
 navTitle: Site & Column Config
-description: Configure site metadata, page headings, and brand icons in site.config.yaml, and organize series in content/columns.yaml.
+description: Configure site metadata, page headings, and brand icons in site.config.yaml, series in content/columns.yaml, and the bookshelf in content/bookshelf.yaml.
 section: getting-started
 order: 3
 ---
 
-Global site copy and appearance settings live in `site.config.yaml` at the repository root, while series definitions live in `content/columns.yaml`. Run `npx garden sync` (or `make dev`) after editing to apply changes.
+Global site copy and appearance settings live in `site.config.yaml` at the repository root, series definitions live in `content/columns.yaml`, and the reading-note shelf lives in `content/bookshelf.yaml`. Run `npx garden sync` (or `make dev`) after editing to apply changes.
 
 ## 1. Full `site.config.yaml` Structure
 
@@ -125,3 +125,42 @@ columns:
 | `status` | No | Status value: `default` (or omitted, shown as "Active"), `ongoing` ("Ongoing"), or `completed` ("Completed"). Legacy Chinese values are still accepted, and any other text is shown verbatim |
 | `cover` | No | Cover image path relative to `content/covers/` |
 | `posts` | Yes | Ordered array of post paths relative to `content/posts/`, without the `.md` extension |
+
+## 3. Configuring the bookshelf (`content/bookshelf.yaml`)
+
+When a site has `content/bookshelf.yaml`, `/bookshelf` renders those books inside the site header and is indexed with the other pages. Without that file, `/bookshelf` is only the package's built-in demo (Chinese click-test, no header, not indexed). A production site supplies the file.
+
+`post` is a path under `content/posts/`, without `.md`. The open book shows the title on the left page and that post's front matter `description` on the right; the note view shows the body. A cover file name is published at `/media/covers/<file>`, the same URL a post's `cover` uses for a file in `content/covers/`. A value that is already `https://…` or starts with `/` is used as written. Omit `cover` to reuse the post's own cover. `color` (`#rgb` or `#rrggbb`) is the spine cloth and the open-page palette, sampled from the cover.
+
+```yaml
+title: Reading notes
+description: Books I have read, and the notes I kept.
+eyebrow: Library
+shelves:
+  - id: recent
+    name: Recent
+    books:
+      - id: ddia
+        title: Designing Data-Intensive Applications
+        author: Martin Kleppmann
+        cover: ddia.jpg
+        color: "#8b3a2f"
+        post: note/ddia
+```
+
+| Field | Required | Description |
+| :--- | :--- | :--- |
+| `title` | Yes | Page title |
+| `description` | No | Page summary |
+| `eyebrow` | No | Small line above the title. Falls back to the site name |
+| `shelves` | Yes | Non-empty list. Each shelf needs `id`, `name`, and a non-empty `books` list |
+| `books[].id` | Yes | Unique across the shelf |
+| `books[].title` | Yes | Title on the left page and the note view |
+| `books[].author` | No | Author |
+| `books[].spine` | No | Spine label. Defaults to `title` |
+| `books[].size` | No | `thin`, `s-short`, `s-mid`, or `s-tall`. Real books default to `s-mid`; filler spines default to `thin` |
+| `books[].cover` | No | File name, or a full URL |
+| `books[].color` | No | Spine and open-page color |
+| `books[].filler` | No | `true`, `sand`, or `cream`. A thin spacer that does not open |
+| `books[].post` | No | Post that supplies the note |
+| `books[].note` | No | Markdown note used only when `post` is absent |

package/package.json

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

package/scripts/build-content.mjs

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import matter from "gray-matter";
 import { marked } from "marked";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -994,6 +994,22 @@ const sitemapEntries = [
     ...thoughts.map((entry) => `/thoughts/${entry.slug}/`),
   ].map(pageAddress)),
 ];
+// A site shelf is a public page. The package demo (no content/bookshelf.yaml) is not.
+// The app imports this module instead of reading the yaml at request time, so the
+// worker preview and the static export both see the same shelf.
+// Forked script copies (pipeline tests) do not ship app/bookshelf; a missing loader
+// means there is no site shelf, same as a package without the file.
+const bookshelfLoaderPath = path.join(gardenPackageRoot, "app", "bookshelf", "load.mjs");
+const loadBookshelf = fs.existsSync(bookshelfLoaderPath)
+  ? (await import(pathToFileURL(bookshelfLoaderPath).href)).loadBookshelf
+  : () => null;
+const bookshelf = loadBookshelf(root, posts);
+fs.mkdirSync(gardenDir, { recursive: true });
+fs.writeFileSync(
+  path.join(gardenDir, "bookshelf.ts"),
+  `// Generated by garden sync. Edit content/bookshelf.yaml instead.\nexport const bookshelf = ${JSON.stringify(bookshelf)} as const;\n`,
+);
+if (bookshelf) sitemapEntries.push(pageAddress("/bookshelf/"));
 // Card URLs in published entries: the only pages the link-card Worker may read.
 fs.writeFileSync(
   path.join(publicRoot, "link-allowlist.json"),

package/scripts/handbook-facts.mjs

@@ -743,13 +743,14 @@ export function checkFileFacts(filePath, content, facts, root = ROOT) {
       const isWorkflow =
         /\b(?:runs-on|steps|jobs|workflow_dispatch|actions\/checkout)\b/u.test(bodyText);
       const isColumnsYaml = /^columns:\s*$/mu.test(bodyText) && /^\s*-\s+slug:/mu.test(bodyText);
+      const isBookshelfYaml = /^shelves:\s*$/mu.test(bodyText) && /^\s*-\s+id:/mu.test(bodyText) && /\bbooks:/u.test(bodyText);
       const isFrontmatter = /^\s*---\s*$/mu.test(bodyText) || (/\bdraft:/u.test(bodyText) && /\btags:/u.test(bodyText));
 
       if (isWorkflow) {
         checkWorkflowRunLines(fence, relFile, facts, issues);
       }
 
-      if (!isWorkflow && !isColumnsYaml && !isFrontmatter) {
+      if (!isWorkflow && !isColumnsYaml && !isBookshelfYaml && !isFrontmatter) {
         try {
           const parsed = parseYaml(bodyText);
           if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {

package/ui/garden/site-nav.mjs

@@ -11,6 +11,18 @@ export const SITE_NAV = [
   { href: "/about/", label: "关于" },
 ];
 
+/**
+ * Header links. A site with `content/bookshelf.yaml` gains 书架; the package
+ * demo (no file) does not advertise a page it only click-tests.
+ */
+export function siteNav({ shelf = false } = {}) {
+  if (!shelf) return SITE_NAV;
+  const entry = { href: "/bookshelf/", label: "书架" };
+  const about = SITE_NAV.findIndex((item) => item.href === "/about/");
+  if (about < 0) return [...SITE_NAV, entry];
+  return [...SITE_NAV.slice(0, about), entry, ...SITE_NAV.slice(about)];
+}
+
 const trim = (value) => (value.length > 1 ? value.replace(/\/+$/u, "") : value);
 
 /**

package/vite.config.ts

@@ -14,9 +14,11 @@ const { d1, r2 } = hostingConfig;
 const siteRoot = gardenSiteRoot();
 const generatedContent = path.join(siteRoot, ".garden", "generated-content.ts");
 const generatedSiteConfig = path.join(siteRoot, ".garden", "site-config.ts");
+const generatedBookshelf = path.join(siteRoot, ".garden", "bookshelf.ts");
 const generatedAliases = {
   "@garden/generated-content": generatedContent,
   "@garden/site-config": generatedSiteConfig,
+  "@garden/bookshelf": generatedBookshelf,
 };
 
 // macOS Seatbelt blocks FSEvents, so Codex previews need polling for HMR.
@@ -67,10 +69,11 @@ function gardenContent() {
       const normalized = id.split("?")[0];
       if (normalized === "@garden/generated-content") return generatedContent;
       if (normalized === "@garden/site-config") return generatedSiteConfig;
+      if (normalized === "@garden/bookshelf") return generatedBookshelf;
       return undefined;
     },
     buildStart() {
-      if (!fs.existsSync(generatedContent) || !fs.existsSync(generatedSiteConfig)) {
+      if (!fs.existsSync(generatedContent) || !fs.existsSync(generatedSiteConfig) || !fs.existsSync(generatedBookshelf)) {
         sync();
       }
     },
@@ -78,13 +81,19 @@ function gardenContent() {
       const contentDir = path.join(siteRoot, "content");
       const configFile = path.join(siteRoot, "site.config.yaml");
       server.watcher.add([contentDir, configFile]);
-      server.watcher.on("change", (file) => {
+      const resyncContent = (file: string) => {
         if (file.startsWith(contentDir) || file === configFile) {
           // While editing, a broken ui block shows as an error card instead of stopping the server.
           sync("preview");
           server.ws.send({ type: "full-reload" });
         }
-      });
+      };
+      server.watcher.on("change", resyncContent);
+      // A new or removed bookshelf.yaml is not a "change". Sync so /bookshelf
+      // switches between the site shelf and the package demo without a restart.
+      const isBookshelf = (file: string) => file.endsWith(`${path.sep}bookshelf.yaml`) || file.endsWith("/bookshelf.yaml");
+      server.watcher.on("add", (file) => { if (isBookshelf(file)) resyncContent(file); });
+      server.watcher.on("unlink", (file) => { if (isBookshelf(file)) resyncContent(file); });
     },
   };
 }