hd-garden 0.9.2 → 0.9.4

package/app/components/bookshelf/index.ts

@@ -4,9 +4,12 @@ export { Bookshelf } from "./Bookshelf";
 export { mountBookshelf } from "./engine";
 export type {
   BookshelfBook,
+  BookshelfBookPost,
   BookshelfFiller,
   BookshelfNote,
+  BookshelfNoteKind,
   BookshelfProps,
   BookshelfShelf,
   BookshelfSize,
+  BookshelfSource,
 } from "./types";

package/app/components/bookshelf/schema.mjs

@@ -7,6 +7,7 @@ export class BookshelfConfigError extends Error {
 }
 
 const SIZES = new Set(["thin", "s-short", "s-mid", "s-tall"]);
+const NOTE_KINDS = new Set(["overview", "excerpt"]);
 
 function record(value, code, message) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new BookshelfConfigError(code, message);
@@ -31,6 +32,71 @@ function parseSize(value, where) {
   throw new BookshelfConfigError("size", `${where} 的 size 只能是 thin、s-short、s-mid 或 s-tall。`);
 }
 
+/** Same path identity as the shelf loader: drop content/posts and .md. */
+function postKey(value) {
+  return value.trim().replaceAll("\\", "/").replace(/^(?:content\/)?posts\//u, "").replace(/\.md$/u, "");
+}
+
+function parsePostEntry(item, where, index) {
+  if (typeof item === "string") {
+    const path = optionalString(item);
+    if (!path) throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 必须是路径。`);
+    return { path };
+  }
+  const entry = record(item, "posts", `${where} 的 posts[${index}] 必须是路径或映射。`);
+  const path = optionalString(entry.path);
+  if (!path) throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 需要 path。`);
+  const kind = optionalString(entry.kind);
+  if (kind && !NOTE_KINDS.has(kind)) {
+    throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 的 kind 只能是 overview 或 excerpt。`);
+  }
+  return kind ? { path, kind } : { path };
+}
+
+/**
+ * `post` is shorthand for one note. `posts` is the list.
+ * When `posts` is set it is the list, and `post` may only repeat the first path.
+ */
+function parsePostList(book, where) {
+  const single = optionalString(book.post);
+  if (book.posts == null) {
+    return single ? { post: single, posts: [{ path: single }] } : { post: undefined, posts: undefined };
+  }
+  if (!Array.isArray(book.posts)) {
+    throw new BookshelfConfigError("posts", `${where} 的 posts 必须是路径数组。`);
+  }
+  const posts = book.posts.map((item, index) => parsePostEntry(item, where, index));
+  if (posts.length === 0) throw new BookshelfConfigError("posts", `${where} 的 posts 不能为空。`);
+  const seenPaths = new Set();
+  for (const entry of posts) {
+    const key = postKey(entry.path);
+    if (seenPaths.has(key)) throw new BookshelfConfigError("posts", `${where} 的 posts 重复引用「${entry.path}」。`);
+    seenPaths.add(key);
+  }
+  if (single && postKey(single) !== postKey(posts[0].path)) {
+    throw new BookshelfConfigError("posts", `${where} 的 post 与 posts 的第一篇不是同一路径。多篇笔记只写 posts。`);
+  }
+  return { post: posts[0].path, posts };
+}
+
+function parseSources(value, where) {
+  if (value == null) return undefined;
+  if (!Array.isArray(value)) throw new BookshelfConfigError("sources", `${where} 的 sources 必须是数组。`);
+  if (value.length === 0) return undefined;
+  return value.map((item, index) => {
+    const source = record(item, "sources", `${where} 的 sources[${index}] 必须是映射。`);
+    const label = optionalString(source.label);
+    const href = optionalString(source.href);
+    if (!label || !href) {
+      throw new BookshelfConfigError("sources", `${where} 的 sources[${index}] 需要 label 和 href。`);
+    }
+    if (!/^(?:https?:\/\/|\/\/|\/(?!\/))/iu.test(href)) {
+      throw new BookshelfConfigError("sources", `${where} 的 sources[${index}] 只接受 http(s) 或以 / 开头的地址。`);
+    }
+    return { label, href };
+  });
+}
+
 function parseBook(value, where, seen) {
   const book = record(value, "book", `${where} 必须是映射。`);
   const id = optionalString(book.id);
@@ -38,6 +104,7 @@ function parseBook(value, where, seen) {
   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);
+  const notes = parsePostList(book, where);
   return {
     id,
     title,
@@ -47,7 +114,9 @@ function parseBook(value, where, seen) {
     cover: optionalString(book.cover),
     color: optionalString(book.color),
     filler: parseFiller(book.filler, where),
-    post: optionalString(book.post),
+    post: notes.post,
+    posts: notes.posts,
+    sources: parseSources(book.sources, where),
     note: typeof book.note === "string" && book.note.trim() ? book.note.trim() : undefined,
   };
 }

package/app/components/bookshelf/schema.ts

@@ -11,7 +11,9 @@ export type BookshelfConfigCode =
   | "size"
   | "filler"
   | "cover"
-  | "post";
+  | "post"
+  | "posts"
+  | "sources";
 
 export interface BookshelfConfigError extends Error {
   readonly code: BookshelfConfigCode;
@@ -23,18 +25,54 @@ export const BookshelfConfigError = ConfigError as unknown as new (
   message: string,
 ) => BookshelfConfigError;
 
+/** `overview` is the reading note (总览). `excerpt` is the quotation note (摘抄). */
+export type BookshelfNoteKind = "overview" | "excerpt";
+
+/** One note bound to a volume. A string in yaml is shorthand for `{ path }`. */
+export type BookshelfFilePost = {
+  /** Path under `content/posts/`, without `.md`. */
+  path: string;
+  kind?: BookshelfNoteKind;
+};
+
+/** Outbound source on the book card. Rendered as a quiet chip, not a button. */
+export type BookshelfFileSource = {
+  label: string;
+  href: string;
+};
+
 /**
- * One volume in `content/bookshelf.yaml`.
+ * One volume in `content/bookshelf.yaml`. One yaml entry is one spine.
+ *
+ * Covers stay on two paths:
+ * - yaml `cover` is the book jacket (Douban). It is the only image for the
+ *   shelf face, the open/close flyer, and the book-hub card.
+ * - a post's front matter `cover` is that note's hero on the article page.
+ *   Never copy a note hero into the jacket slot.
+ * - omit yaml `cover` and the jacket falls back to the first note's cover.
  *
- * 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.
+ * Notes:
+ * - `post: path` is shorthand for `posts: [path]`.
+ * - `posts` is the note list, in order. `kind: overview | excerpt` labels the
+ *   hub card 总览 or 摘抄. A bare string is a path with no kind.
+ * - when `posts` is set, `post` is optional. If both are set, `post` must be
+ *   the same path as `posts[0]`. Otherwise the shelf is rejected.
+ * - one note: the shelf opens that note as it does today (extract flyer, note,
+ *   return flyer). There is no book hub.
+ * - two or more notes: a spine click plays the same extract flyer and lands
+ *   on `/bookshelf/<id>` (本书). It does not open `posts[0]`.
+ *   The hub card is the locked book-multi layout: the jacket slot is 148px
+ *   wide, the image fills that width, and the height follows the file's ratio.
+ *   There is no plate behind the jacket. A Douban scan's white border is
+ *   cropped in the jacket file before it is committed; the build copies that
+ *   file into `/media/covers/` unchanged.
+ *   「我的笔记」 lists the notes. A note card is an ordinary link to that
+ *   article; article ↔ list does not play the flyer. Returning from the hub
+ *   to the shelf plays the close flyer. A single note uses that same flyer.
+ * - `sources` are optional `{ label, href }` chips. The hub shows 豆瓣 and PDF
+ *   only. The PDF chip carries the caption 「（仅分享，侵权删）」. No chapter list.
+ * - `note` is Markdown used only when the book has no posts.
  * - `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;
@@ -42,10 +80,14 @@ export type BookshelfFileBook = {
   author?: string;
   spine?: string;
   size?: BookshelfSize;
+  /** Book jacket. File name under `content/covers/`, or a full URL. */
   cover?: string;
   color?: string;
   filler?: BookshelfFiller;
+  /** Shorthand for a single note. Equal to `posts[0].path` after parsing. */
   post?: string;
+  posts?: BookshelfFilePost[];
+  sources?: BookshelfFileSource[];
   note?: string;
 };
 

package/app/components/bookshelf/types.ts

@@ -2,12 +2,38 @@ import type { BookshelfFiller, BookshelfSize } from "./model";
 
 export type { BookshelfFiller, BookshelfSize };
 
+/** `overview` prints as 总览 on the hub. `excerpt` prints as 摘抄. */
+export type BookshelfNoteKind = "overview" | "excerpt";
+
+/** One reading note on a volume. Order is the yaml order. */
+export type BookshelfBookPost = {
+  /** `content/posts` path without `.md`. */
+  path: string;
+  title: string;
+  kind?: BookshelfNoteKind;
+  /** Front matter description. The hub card summary. */
+  summary?: string;
+  date?: string;
+  /** Same count the article page shows. */
+  words?: number;
+  /** Article address. The shelf page fills this. */
+  href?: string;
+};
+
+/** Quiet source chip on the book hub (豆瓣, PDF). */
+export type BookshelfSource = {
+  label: string;
+  href: string;
+};
+
 /**
  * One volume on the shelf.
+ * `cover` is the book jacket only: shelf face, open/close flyer, and the hub card.
  * `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.
+ * A note's own hero stays on the article page. It is never this field when yaml `cover` is set.
+ * `color` is the spine cloth and the open-page palette. Sample it from the jacket.
  */
 export type BookshelfBook = {
   id: string;
@@ -18,10 +44,18 @@ export type BookshelfBook = {
   cover?: boolean | string;
   color?: string;
   filler?: BookshelfFiller;
-  /** Key into the notes map. Null means the demo placeholder paragraph. */
+  /**
+   * Key into the notes map for a single-note book.
+   * Null on a multi-note book: that book opens `/bookshelf/<id>` instead.
+   */
   note?: string | null;
-  /** `content/posts` path without `.md`, when the note is a post. */
+  /** Primary note path. Set only when the book has one note. */
   post?: string;
+  /** Every note on this volume, primary first. */
+  posts?: BookshelfBookPost[];
+  /** `/bookshelf/<id>`. Set only when `posts` has two or more notes. */
+  hub?: string;
+  sources?: BookshelfSource[];
   /** Full-note address, shaped for this build. Set when `post` is set. */
   href?: string;
 };
@@ -52,4 +86,9 @@ export type BookshelfProps = {
    * unset and keeps its own full-viewport frame.
    */
   embedded?: boolean;
+  /**
+   * Open `/bookshelf/<id>` already on the hub, with the shelf parked under it
+   * so the return flyer can run. A shelf click does not use this.
+   */
+  initialHub?: string;
 };

package/app/lib/i18n.ts

@@ -299,6 +299,11 @@ const zh = {
   adminTitlePreview: "草稿预览",
   a2IndexTitle: "A2 对照",
   a2IndexDeck: "对照参考文章的版式。正文没有改字。",
+  bookHubCurrent: "本书",
+  bookHubNotes: "我的笔记",
+  bookHubOverview: "总览",
+  bookHubExcerpt: "摘抄",
+  bookHubPdfNote: "（仅分享，侵权删）",
 };
 
 const en: typeof zh = {
@@ -582,6 +587,11 @@ const en: typeof zh = {
   adminTitlePreview: "Draft Preview",
   a2IndexTitle: "A2 Parity",
   a2IndexDeck: "Layout comparison against reference articles. Body text is unchanged.",
+  bookHubCurrent: "This book",
+  bookHubNotes: "My notes",
+  bookHubOverview: "Overview",
+  bookHubExcerpt: "Excerpt",
+  bookHubPdfNote: "(shared only — removed if it infringes)",
 };
 
 export const UI_STRINGS = { zh, en } as const;

package/app/sitemap.ts

@@ -4,6 +4,7 @@ import { columnHref, columns, postHref, posts, thoughtHref } from "./lib/content
 import { absoluteUrl, getSiteUrl } from "./lib/site";
 import { getPublishedThoughts } from "./lib/public-thoughts";
 import { siteHref } from "./lib/site-href";
+import type { BookshelfBook, BookshelfShelf } from "./components/bookshelf/types";
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const baseUrl = await getSiteUrl();
@@ -17,6 +18,13 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
     { 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 }] : []),
+    ...(bookshelf
+      ? bookshelf.catalog.flatMap((row: BookshelfShelf) =>
+          row.books
+            .filter((book: BookshelfBook) => typeof book.hub === "string")
+            .map((book: BookshelfBook) => ({ path: book.hub ?? "/bookshelf", priority: 0.55, changeFrequency: "weekly" as const })),
+        )
+      : []),
   ].map((route) => ({
     url: absoluteUrl(siteHref(route.path), baseUrl),
     changeFrequency: route.changeFrequency,

package/app/styles/shell.css

@@ -434,6 +434,43 @@ html[data-theme="dark"] .sh-repos > li.sk::after{background:linear-gradient(90de
   .sh-series.no-cover h2,.sh-series.no-cover .count{grid-column:1 / -1;grid-row:auto}
 }
 
+/* Book hub (本书), locked to tip book-multi-20261029c. Width is fixed; height follows the jacket. */
+.book-hub{width:min(100%,740px);padding:40px 0 72px}
+.book-hub-crumb{margin:0 0 28px;font-size:12px;color:var(--faint,#a09b91);letter-spacing:.06em}
+.book-hub-crumb a{color:inherit;text-decoration:none}
+.book-hub-crumb a:hover{color:var(--ink)}
+.book-hub-crumb [aria-current="page"]{color:var(--faint,#a09b91)}
+.book-hub-card{display:flex;gap:28px;align-items:flex-start;margin:0 0 40px}
+.book-hub-cover{width:148px;flex-shrink:0;height:auto;min-height:0;aspect-ratio:auto;border-radius:0;overflow:visible;background:none;box-shadow:none;line-height:0;padding:0}
+.book-hub-cover img{display:block;width:148px;max-width:none;height:auto;aspect-ratio:auto;object-fit:unset;background:none;border-radius:4px;box-shadow:0 10px 24px rgba(40,30,20,.10)}
+.book-hub-meta{flex:1;min-width:0;padding-top:4px}
+.book-hub-meta h1{margin:0 0 10px;font-family:var(--serif);font-size:clamp(26px,4vw,34px);font-weight:600;line-height:1.25;letter-spacing:-.01em;color:var(--ink)}
+.book-hub-author{margin:0 0 18px;font-size:14px;color:var(--muted)}
+.book-hub-sources{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
+.book-hub-source{display:inline-flex;align-items:center;gap:2px}
+.book-hub-chip{display:inline-flex;align-items:center;gap:4px;padding:4px 10px;border-radius:999px;background:#f3efe6;color:var(--muted);font-size:12px;line-height:1.4;text-decoration:none;border:1px solid transparent}
+html[data-theme="dark"] .book-hub-chip{background:var(--chip)}
+.book-hub-chip:hover{color:var(--ink);border-color:var(--rule)}
+.book-hub-chip .ext{font-size:11px;opacity:.7}
+.book-hub-source-note{font-size:11px;color:var(--faint,#a09b91);letter-spacing:.02em;line-height:1.4}
+.book-hub-notes-head{margin:0 0 14px;font:400 12px/1.4 var(--sans);color:var(--faint,#a09b91);letter-spacing:.12em}
+.book-hub-notes{display:flex;flex-direction:column;gap:12px;margin:0;padding:0;list-style:none}
+.book-hub-note{display:block;width:100%;text-align:left;padding:18px 20px;background:#fffcf7;border:1px solid var(--rule);border-radius:10px;text-decoration:none;color:inherit}
+html[data-theme="dark"] .book-hub-note{background:var(--card)}
+@media (hover:hover){
+  .book-hub-note:hover{border-color:#d5d0c4;box-shadow:0 6px 16px rgba(40,30,20,.05)}
+  html[data-theme="dark"] .book-hub-note:hover{border-color:var(--rule-strong);box-shadow:none}
+}
+.book-hub-note-label{margin:0 0 6px;font-size:11px;color:var(--faint,#a09b91);letter-spacing:.08em}
+.book-hub-note h3{margin:0 0 8px;font:500 16px/1.45 var(--sans);color:var(--ink)}
+.book-hub-note-sum{margin:0 0 12px;font-size:13px;line-height:1.65;color:var(--muted)}
+.book-hub-note-meta{margin:0;font-size:12px;color:var(--faint,#a09b91)}
+@media (max-width:560px){
+  .book-hub{padding:28px 0 64px}
+  .book-hub-card{flex-direction:column;gap:18px}
+  .book-hub-cover,.book-hub-cover img{width:120px}
+}
+
 .sh-row .incol{grid-column:2;justify-self:start;position:relative;z-index:1;margin-top:4px;font-size:var(--fs-meta);line-height:1.6;color:var(--muted);text-decoration:none}
 @media (hover:hover){.sh-row .incol:hover{color:var(--blue);text-decoration:underline;text-underline-offset:3px}}
 .is-compact .sh-row .incol{display:none}

package/docs/handbook/config.md

@@ -130,7 +130,9 @@ columns:
 
 `/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`），用来画书脊和打开后的纸页。
+架上每一条 `books` 是一本书。`post: note/ddia` 是只有一篇笔记时的简写。一本书有多篇笔记时写 `posts`，点书脊播放抽书动画，落到 `/bookshelf/<id>`（本书），不打开第一篇。从本书页回到书架播放合上动画。本书页左边是书衣（宽 148，高度跟图片走），右边是书名、作者，以及豆瓣和 PDF 两枚出处胶囊；PDF 后面有一行「（仅分享，侵权删）」。下面是「我的笔记」，点进去才是文章，这一步没有飞页。单篇笔记仍走原来的抽书和合上。
+
+`cover` 是书衣，只给书架、抽书飞页和本书页用。文件放在 `content/covers/`，构建时会复制到 `/media/covers/`，即使没有任何博文的 front matter 引用这个文件名。豆瓣封面四周的白边在放进 `content/covers/` 之前裁好，构建不会再改像素。笔记页的横幅仍是各篇 front matter 的 `cover`，不要把那张图填进书衣。yaml 不写 `cover` 时，书衣才沿用第一篇的封面。`color`（`#rgb` 或 `#rrggbb`）画书脊和单篇打开后的纸页。
 
 ```yaml
 title: 读书笔记
@@ -146,6 +148,20 @@ shelves:
         cover: ddia.jpg
         color: "#8b3a2f"
         post: note/ddia
+      - id: unit-testing
+        title: Unit Testing
+        cover: unit-testing.jpg
+        color: "#1a2744"
+        sources:
+          - label: 豆瓣
+            href: https://book.douban.com/subject/00000000/
+          - label: PDF
+            href: https://example.com/unit-testing.pdf
+        posts:
+          - path: note/note-unit-testing
+            kind: overview
+          - path: note/note-unit-testing-excerpt
+            kind: excerpt
 ```
 
 | 字段 | 必填 | 说明 |
@@ -159,8 +175,10 @@ shelves:
 | `books[].author` | 否 | 作者 |
 | `books[].spine` | 否 | 书脊文字，默认同 `title` |
 | `books[].size` | 否 | `thin`、`s-short`、`s-mid`、`s-tall`。普通书默认 `s-mid`，占位薄册默认 `thin` |
-| `books[].cover` | 否 | 文件名，或完整 URL |
-| `books[].color` | 否 | 书脊和打开后的纸色 |
+| `books[].cover` | 否 | 书衣。文件名或完整 URL。写了就只用它 |
+| `books[].color` | 否 | 书脊和单篇打开后的纸色 |
 | `books[].filler` | 否 | `true`、`sand` 或 `cream`，占位薄册，不能打开 |
-| `books[].post` | 否 | 笔记正文所在的博文 |
-| `books[].note` | 否 | 没有 `post` 时直接写的 Markdown 笔记 |
+| `books[].post` | 否 | 单篇笔记的简写 |
+| `books[].posts` | 否 | 同一本书下的笔记。`kind` 为 `overview`（总览）或 `excerpt`（摘抄）。两篇及以上打开本书页 |
+| `books[].sources` | 否 | 出处。本书页只显示「豆瓣」和「PDF」 |
+| `books[].note` | 否 | 没有笔记路径时直接写的 Markdown |

package/docs/handbook/en/config.md

@@ -130,7 +130,9 @@ columns:
 
 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.
+Each `books` entry is one volume. `post: note/ddia` is the one-note shorthand. Several notes use `posts`. Clicking that spine plays the extract animation and lands on `/bookshelf/<id>`. It does not open the first note. Returning from that page to the shelf plays the close animation. The book page shows a 148px-wide jacket (height follows the image), the title, the author, and only the Douban and PDF chips. The PDF chip is followed by a short sharing note. My notes lists the notes; each card is a normal link to the article and does not play the flyer. A single note still uses the extract and return animation.
+
+`cover` is the jacket for the shelf, the flyer, and the book page. The file lives in `content/covers/` and the build copies it to `/media/covers/`, even when no post front matter names that file. Crop a Douban scan's white margin before committing the file; the build does not change pixels. A note's hero stays that post's front matter `cover`. Omit the jacket and it falls back to the first note's cover. `color` (`#rgb` or `#rrggbb`) is the spine and the single-note open page.
 
 ```yaml
 title: Reading notes
@@ -146,6 +148,20 @@ shelves:
         cover: ddia.jpg
         color: "#8b3a2f"
         post: note/ddia
+      - id: unit-testing
+        title: Unit Testing
+        cover: unit-testing.jpg
+        color: "#1a2744"
+        sources:
+          - label: Douban
+            href: https://book.douban.com/subject/00000000/
+          - label: PDF
+            href: https://example.com/unit-testing.pdf
+        posts:
+          - path: note/note-unit-testing
+            kind: overview
+          - path: note/note-unit-testing-excerpt
+            kind: excerpt
 ```
 
 | Field | Required | Description |
@@ -159,8 +175,10 @@ shelves:
 | `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[].cover` | No | Jacket. File name or full URL. When set, it is the only jacket |
+| `books[].color` | No | Spine and single-note 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 |
+| `books[].post` | No | Shorthand for one note |
+| `books[].posts` | No | Notes on this volume. `kind` is `overview` or `excerpt`. Two or more open the book page |
+| `books[].sources` | No | Sources. The book page shows Douban and PDF only |
+| `books[].note` | No | Markdown used only when the book names no posts |

package/package.json

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

package/scripts/bookshelf-covers.mjs

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveBookshelfCover } from "../app/components/bookshelf/catalog.mjs";
+import { BookshelfConfigError } from "../app/components/bookshelf/schema.mjs";
+
+/**
+ * Where a `books[].cover` value sits under `content/covers/`.
+ * Full URLs are not local files. `/media/covers/…` is the published name of a file in that directory.
+ * Returns null when there is nothing to copy.
+ */
+export function bookshelfJacketSource(cover) {
+  const value = String(cover ?? "").trim();
+  if (!value) return null;
+  if (/^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(value) || value.startsWith("data:")) return null;
+  if (value.startsWith("/")) {
+    const marker = "/media/covers/";
+    const index = value.indexOf(marker);
+    if (index < 0) return null;
+    return safeCoverRelative(decodeURIComponent(value.slice(index + marker.length)).split(/[?#]/u)[0], value);
+  }
+  let relative = value.replace(/^\.\//u, "").replaceAll("\\", "/").split(/[?#]/u)[0];
+  if (relative.startsWith("covers/")) relative = relative.slice("covers/".length);
+  return safeCoverRelative(relative, value);
+}
+
+function safeCoverRelative(relative, original) {
+  if (!relative || relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new BookshelfConfigError("cover", `书衣 ${original} 必须是 content/covers 下的文件。`);
+  }
+  return relative;
+}
+
+/**
+ * Copy every local book jacket into `public/media/covers/`, including filenames
+ * that no post front matter mentions. Bytes are copied as stored (white borders
+ * are cropped in the file itself, not here).
+ */
+export function publishBookshelfJackets(config, { coversDir, mediaDir }) {
+  const copied = [];
+  for (const shelf of config.shelves ?? []) {
+    for (const book of shelf.books ?? []) {
+      if (!book.cover) continue;
+      const sourceRel = bookshelfJacketSource(book.cover);
+      if (!sourceRel) continue;
+      const published = resolveBookshelfCover(book.cover, book.id);
+      if (!published?.startsWith("/media/covers/")) continue;
+      const publicRel = decodeURIComponent(published.slice("/media/covers/".length)).split(/[?#]/u)[0];
+      const source = path.join(coversDir, ...sourceRel.split("/"));
+      const destination = path.join(mediaDir, ...publicRel.split("/"));
+      if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+        throw new BookshelfConfigError(
+          "cover",
+          `content/covers 里没有书衣 ${sourceRel}。bookshelf.yaml 的 cover 会原样复制到 /media/covers/。`,
+        );
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.copyFileSync(source, destination);
+      copied.push(publicRel);
+    }
+  }
+  return copied;
+}

package/scripts/build-content.mjs

@@ -1009,7 +1009,21 @@ 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/"));
+if (bookshelf) {
+  sitemapEntries.push(pageAddress("/bookshelf/"));
+  for (const row of bookshelf.catalog ?? []) {
+    for (const book of row.books ?? []) {
+      if (typeof book.hub === "string" && book.hub.startsWith("/")) sitemapEntries.push(pageAddress(book.hub));
+    }
+  }
+  const { publishBookshelfJackets } = await import(pathToFileURL(path.join(gardenPackageRoot, "scripts", "bookshelf-covers.mjs")).href);
+  const { parseBookshelfConfig } = await import(pathToFileURL(path.join(gardenPackageRoot, "app", "components", "bookshelf", "schema.mjs")).href);
+  const coverConfig = parseBookshelfConfig(parseYaml(fs.readFileSync(path.join(contentRoot, "bookshelf.yaml"), "utf8")));
+  publishBookshelfJackets(coverConfig, {
+    coversDir: path.join(contentRoot, "covers"),
+    mediaDir: path.join(generatedMediaRoot, "covers"),
+  });
+}
 // Card URLs in published entries: the only pages the link-card Worker may read.
 fs.writeFileSync(
   path.join(publicRoot, "link-allowlist.json"),