hd-garden 0.9.2 → 0.9.3

package/app/bookshelf/[bookId]/page.tsx

@@ -0,0 +1,55 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { bookshelf } from "@garden/bookshelf";
+import { BookHub } from "../../components/bookshelf/BookHub";
+import { pageAlternates } from "../../lib/page-alternates";
+import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../ui/garden/static-params.mjs";
+import type { BookshelfBook } from "../../components/bookshelf/types";
+
+function hubBooks(): { shelfTitle: string; book: BookshelfBook }[] {
+  if (!bookshelf) return [];
+  const found: { shelfTitle: string; book: BookshelfBook }[] = [];
+  for (const row of bookshelf.catalog) {
+    for (const book of row.books) {
+      if ((book.posts?.length ?? 0) > 1) found.push({ shelfTitle: bookshelf.title, book });
+    }
+  }
+  return found;
+}
+
+export function generateStaticParams() {
+  return staticParams(
+    hubBooks().map(({ book }) => ({ bookId: book.id })),
+    { bookId: STATIC_PLACEHOLDER },
+  );
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ bookId: string }>;
+}): Promise<Metadata> {
+  const { bookId } = await params;
+  const found = hubBooks().find((item) => item.book.id === bookId);
+  if (!found) return {};
+  return {
+    title: found.book.title,
+    description: found.book.posts?.find((post) => post.summary)?.summary,
+    alternates: pageAlternates(`/bookshelf/${found.book.id}`),
+  };
+}
+
+/** `/bookshelf/<id>` — one multi-note volume. Single-note books stay on the shelf. */
+export default async function BookHubPage({
+  params,
+}: {
+  params: Promise<{ bookId: string }>;
+}) {
+  const { bookId } = await params;
+  const found = hubBooks().find((item) => item.book.id === bookId);
+  if (!found) {
+    if (isStaticPlaceholder(bookId)) return null;
+    notFound();
+  }
+  return <BookHub shelfTitle={found.shelfTitle} book={found.book} />;
+}

package/app/bookshelf/load.mjs

@@ -13,7 +13,8 @@ export function bookshelfConfigPath(root = gardenSiteRoot()) {
 /**
  * The site shelf, or null when `content/bookshelf.yaml` is absent.
  * Absent means the package demo (click-test only). A file here is the live shelf:
- * each book's `post` is read from `content/posts` and turned into note HTML.
+ * each book's `post` or `posts` is read from `content/posts`. One note becomes
+ * the open-book HTML. Several notes stay on the book for `/bookshelf/<id>`.
  * `preparedPosts`, when passed, are the sync pipeline's posts (rewritten asset
  * URLs). Otherwise the markdown files are read directly.
  * Throws `BookshelfConfigError` when the file, a cover, or a post path is broken.
@@ -35,22 +36,33 @@ export function loadBookshelf(root = gardenSiteRoot(), preparedPosts) {
       title: post.title,
       description: post.description,
       cover: post.cover,
+      date: typeof post.date === "string" ? post.date : undefined,
       content: post.content,
     }))
     : readReferencedPosts(root, config);
   return bookshelfMountFromFile(config, sources);
 }
 
+function referencedPostPaths(book) {
+  if (Array.isArray(book.posts) && book.posts.length > 0) {
+    return book.posts
+      .map((entry) => (typeof entry === "string" ? entry : entry?.path))
+      .filter((path) => typeof path === "string" && path.trim());
+  }
+  return book.post ? [book.post] : [];
+}
+
 function readReferencedPosts(root, config) {
   const seen = new Set();
   const posts = [];
   for (const shelf of config.shelves) {
     for (const book of shelf.books) {
-      if (!book.post) continue;
-      const relative = normalizeBookshelfPostPath(book.post);
-      if (seen.has(relative)) continue;
-      seen.add(relative);
-      posts.push(readPost(root, relative));
+      for (const entry of referencedPostPaths(book)) {
+        const relative = normalizeBookshelfPostPath(entry);
+        if (seen.has(relative)) continue;
+        seen.add(relative);
+        posts.push(readPost(root, relative));
+      }
     }
   }
   return posts;
@@ -85,6 +97,7 @@ function readPost(root, postPath) {
     title: optionalString(data.title),
     description: optionalString(data.description),
     cover: optionalString(data.cover),
+    date: optionalDate(data.date),
     content: parsed.content,
   };
 }
@@ -94,3 +107,8 @@ function optionalString(value) {
   const trimmed = value.trim();
   return trimmed ? trimmed : undefined;
 }
+
+function optionalDate(value) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  return optionalString(value);
+}

package/app/components/bookshelf/BookHub.tsx

@@ -0,0 +1,142 @@
+import Link from "next/link";
+import { siteHref } from "../../lib/site-href";
+import { ui } from "../../lib/i18n";
+import type { BookshelfBook, BookshelfBookPost, BookshelfNoteKind, BookshelfSource } from "./types";
+
+function day(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value.slice(0, 10);
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+function kindLabel(kind: BookshelfNoteKind | undefined) {
+  const t = ui();
+  switch (kind) {
+    case "overview":
+      return t.bookHubOverview;
+    case "excerpt":
+      return t.bookHubExcerpt;
+    case undefined:
+      return "";
+    default: {
+      const unexpected: never = kind;
+      return unexpected;
+    }
+  }
+}
+
+function sourceHref(href: string) {
+  if (href.startsWith("/") && !href.startsWith("//")) return siteHref(href);
+  return href;
+}
+
+function isExternal(href: string) {
+  return /^(?:https?:)?\/\//iu.test(href);
+}
+
+/** Hub chips are Douban and PDF. The Chinese label is the zh shelf; English sites write Douban. */
+function isDoubanChip(label: string) {
+  return label === "豆瓣" || /^douban$/iu.test(label);
+}
+
+function hubSources(sources: readonly BookshelfSource[] | undefined) {
+  const list = sources ?? [];
+  const douban = list.filter((source) => isDoubanChip(source.label));
+  const pdf = list.filter((source) => /pdf/iu.test(source.label));
+  return [...douban, ...pdf];
+}
+
+function NoteCard({ entry }: { entry: BookshelfBookPost }) {
+  const t = ui();
+  const label = kindLabel(entry.kind);
+  const href = entry.href ?? siteHref(`/blog/${entry.path}`);
+  const when = entry.date ? day(entry.date) : "";
+  const count = entry.words ? t.wordCount(entry.words) : "";
+  return (
+    <Link className="book-hub-note" href={href}>
+      {label ? <p className="book-hub-note-label">{label}</p> : null}
+      <h3>{entry.title}</h3>
+      {entry.summary ? <p className="book-hub-note-sum">{entry.summary}</p> : null}
+      {when || count ? (
+        <p className="book-hub-note-meta">
+          {when}
+          {when && count ? " · " : null}
+          {count}
+        </p>
+      ) : null}
+    </Link>
+  );
+}
+
+function SourceChips({ sources }: { sources: readonly BookshelfSource[] }) {
+  const shown = hubSources(sources);
+  if (!shown.length) return null;
+  const t = ui();
+  return (
+    <div className="book-hub-sources">
+      {shown.map((source) => {
+        const href = sourceHref(source.href);
+        const external = isExternal(source.href);
+        const pdf = /pdf/iu.test(source.label);
+        return (
+          <span className="book-hub-source" key={`${source.label}\u0000${source.href}`}>
+            <a
+              className="book-hub-chip"
+              href={href}
+              {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+            >
+              {source.label}
+              <span className="ext" aria-hidden="true">↗</span>
+            </a>
+            {pdf ? <span className="book-hub-source-note">{t.bookHubPdfNote}</span> : null}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+/** Book hub (本书). Multi-note volumes land here; a note card is a plain article link. */
+export function BookHub({ shelfTitle, book }: { shelfTitle: string; book: BookshelfBook }) {
+  const t = ui();
+  const jacket = typeof book.cover === "string" ? book.cover : "";
+  const posts = book.posts ?? [];
+  return (
+    <main className="sh-main book-hub" id="content">
+      <p className="book-hub-crumb">
+        <Link href={siteHref("/columns")}>{t.homeColumns}</Link>
+        <span aria-hidden="true"> · </span>
+        <Link href={siteHref("/bookshelf")}>{shelfTitle}</Link>
+        <span aria-hidden="true"> · </span>
+        <span aria-current="page">{t.bookHubCurrent}</span>
+      </p>
+
+      <section className="book-hub-card" aria-labelledby="book-hub-title">
+        {jacket ? (
+          <div className="book-hub-cover">
+            <img src={jacket} alt={t.coverLabel(book.title)} width={148} />
+          </div>
+        ) : null}
+        <div className="book-hub-meta">
+          <h1 id="book-hub-title">{book.title}</h1>
+          {book.author ? <p className="book-hub-author">{book.author}</p> : null}
+          <SourceChips sources={book.sources ?? []} />
+        </div>
+      </section>
+
+      <h2 className="book-hub-notes-head">{t.bookHubNotes}</h2>
+      <ul className="book-hub-notes">
+        {posts.map((entry) => (
+          <li key={entry.path}>
+            <NoteCard entry={entry} />
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/app/components/bookshelf/Bookshelf.tsx

@@ -12,9 +12,20 @@ function withNoteLinks(catalog: BookshelfShelf[] | undefined) {
   if (!catalog) return catalog;
   return catalog.map((row) => ({
     ...row,
-    books: row.books.map((book) =>
-      book.post ? { ...book, href: siteHref(`/blog/${book.post}`) } : book,
-    ),
+    books: row.books.map((book) => {
+      const posts = book.posts?.map((entry) => ({
+        ...entry,
+        href: siteHref(`/blog/${entry.path}`),
+      }));
+      const hub = book.hub ? siteHref(book.hub) : undefined;
+      if (!book.post && !posts?.length && !hub) return book;
+      return {
+        ...book,
+        ...(book.post ? { href: siteHref(`/blog/${book.post}`) } : {}),
+        ...(posts?.length ? { posts } : {}),
+        ...(hub ? { hub } : {}),
+      };
+    }),
   }));
 }
 

package/app/components/bookshelf/catalog.mjs

@@ -1,4 +1,5 @@
 import { marked } from "marked";
+import { searchableText } from "../../../ui/garden/search-index.mjs";
 import { BookshelfConfigError } from "./schema.mjs";
 
 /**
@@ -6,10 +7,13 @@ import { BookshelfConfigError } from "./schema.mjs";
  * Built only from `content/bookshelf.yaml` and the posts it names.
  * The package demo is a separate path: this module never reads it.
  *
- * `post` is a `content/posts` path without `.md`. Its front matter description
- * leads the note HTML so the open book's right page is that summary.
- * A cover file name is published at `/media/covers/<file>` (same stem cleanup
- * as content sync). A full URL or a path starting with `/` is kept.
+ * `post` is shorthand for one note. `posts` is the list. A single note still
+ * becomes the open-book body. Two or more notes do not: the book carries `hub`
+ * (`/bookshelf/<id>`) and the shelf navigates there instead of opening `posts[0]`.
+ *
+ * The jacket is yaml `cover` only. A post cover is that note's hero and is
+ * copied onto the book only when yaml `cover` is omitted, and then only from
+ * the first note. A file name is published at `/media/covers/<file>`.
  */
 
 const WIDGET_FENCE = /```(?:garden|ui-error|ui|intent|widget)(?:[ \t]+[^\n]*)?\r?\n[\s\S]*?```/gu;
@@ -29,6 +33,14 @@ export function resolveBookshelfCover(cover, where = "cover") {
   return `/media/covers/${parts.map(publishCoverSegment).join("/")}`;
 }
 
+/** Book hub for a multi-note volume. One path segment, the book id. */
+export function bookshelfHubPath(id) {
+  if (typeof id !== "string" || !id || /[\\/]/.test(id) || id === "." || id === "..") {
+    throw new BookshelfConfigError("book", `本书页的 id「${id ?? ""}」必须是单一路径段。`);
+  }
+  return `/bookshelf/${encodeURIComponent(id)}`;
+}
+
 /** `content/posts` path, without `.md`. Rejects anything that leaves that directory. */
 export function normalizeBookshelfPostPath(value) {
   const relative = value
@@ -63,19 +75,64 @@ export function bookshelfMountFromFile(file, posts) {
   };
 }
 
-function toCatalogBook(book, byPath, notes) {
-  const post = book.post ? byPath.get(normalizeBookshelfPostPath(book.post)) : undefined;
-  if (book.post && !post) {
-    throw new BookshelfConfigError("post", `书架引用的博文 ${book.post} 没有读到。`);
+function bookPostRefs(book) {
+  if (Array.isArray(book.posts) && book.posts.length > 0) {
+    return book.posts.map((entry) => (
+      typeof entry === "string" ? { path: entry } : { path: entry?.path, kind: entry?.kind }
+    ));
   }
-  const cover = resolveBookshelfCover(book.cover, book.id) ?? (post ? resolveBookshelfCover(post.cover, book.id) : undefined);
-  const body = post
-    ? renderNoteHtml(post.content, post.description)
-    : book.note
+  if (typeof book.post === "string" && book.post.trim()) return [{ path: book.post.trim() }];
+  return [];
+}
+
+/** Same count the article page prints (`estimateWordCount`). */
+function noteWordCount(markdown) {
+  const text = searchableText(markdown ?? "");
+  const han = text.match(/[\u3400-\u9fff]/gu)?.length ?? 0;
+  const other = text.replace(/[\u3400-\u9fff]/gu, " ").match(/[\p{L}\p{N}]+/gu)?.length ?? 0;
+  return han + other;
+}
+
+/** Jacket: yaml cover when set. Otherwise the first note's cover, never a later note's. */
+function jacketFor(book, primary) {
+  if (book.cover) return resolveBookshelfCover(book.cover, book.id);
+  if (primary?.cover) return resolveBookshelfCover(primary.cover, book.id);
+  return undefined;
+}
+
+function toCatalogBook(book, byPath, notes) {
+  const refs = bookPostRefs(book);
+  const paths = refs.map((ref) => normalizeBookshelfPostPath(ref.path));
+  const sources = paths.map((relative, index) => {
+    const post = byPath.get(relative);
+    if (!post) throw new BookshelfConfigError("post", `书架引用的博文 ${refs[index].path} 没有读到。`);
+    return post;
+  });
+  const primary = sources[0];
+  const multi = sources.length > 1;
+  const cover = jacketFor(book, primary);
+  // A multi-note book opens on the hub. Its note bodies stay on the article pages.
+  const body = !multi && primary
+    ? renderNoteHtml(primary.content, primary.description)
+    : !multi && book.note
       ? renderNoteHtml(book.note)
       : "";
   const note = body ? book.id : null;
-  if (note) notes[book.id] = { title: book.title, body, summary: post?.description };
+  if (note) notes[book.id] = { title: book.title, body, summary: primary?.description };
+  const posts = sources.map((source, index) => {
+    const words = noteWordCount(source.content);
+    const title = (typeof source.title === "string" && source.title.trim()) || (index === 0 ? book.title : paths[index]);
+    const summary = typeof source.description === "string" ? source.description.trim() : "";
+    const date = typeof source.date === "string" ? source.date.trim() : "";
+    return {
+      path: paths[index],
+      title,
+      ...(refs[index].kind ? { kind: refs[index].kind } : {}),
+      ...(summary ? { summary } : {}),
+      ...(date ? { date } : {}),
+      ...(words > 0 ? { words } : {}),
+    };
+  });
   return {
     id: book.id,
     title: book.title,
@@ -85,7 +142,10 @@ function toCatalogBook(book, byPath, notes) {
     cover: cover ?? false,
     color: book.color,
     filler: book.filler,
-    post: book.post ? normalizeBookshelfPostPath(book.post) : undefined,
+    post: !multi && paths[0] ? paths[0] : undefined,
+    posts: posts.length ? posts : undefined,
+    hub: multi ? bookshelfHubPath(book.id) : undefined,
+    sources: Array.isArray(book.sources) && book.sources.length ? book.sources : undefined,
     note,
   };
 }

package/app/components/bookshelf/catalog.ts

@@ -4,6 +4,10 @@ import type { BookshelfNote, BookshelfShelf } from "./types";
  * Site shelf ready for `<Bookshelf catalog notes />`.
  * The runtime lives in `catalog.mjs` (node tests and the page share it).
  * The package demo is not an input.
+ *
+ * A book's `cover` is the jacket. A post's `cover` on `BookshelfPostSource` is
+ * that note's hero and is used as the jacket only when the yaml book omits
+ * `cover`. Multi-note books set `hub` (`/bookshelf/<id>`) and do not fill `notes`.
  */
 export type BookshelfMount = {
   title: string;

package/app/components/bookshelf/engine.ts

@@ -677,18 +677,31 @@ export function mountBookshelf(root, options = {}) {
     collapseToken += 1;
   }
 
+  // Multi-note books leave the shelf for /bookshelf/<id>. No extract flyer.
+  function leaveForHub(book) {
+    const posts = book && Array.isArray(book.posts) ? book.posts : [];
+    const href = book && typeof book.hub === "string" ? book.hub : "";
+    if (posts.length < 2 || !href) return false;
+    const y = scrollLock ? scrollLock.y : readScroll().y;
+    try { sessionStorage.setItem("garden-bookshelf-scroll", String(y)); } catch (_) {}
+    window.location.assign(href);
+    return true;
+  }
+
   async function onCoverClick(id, el) {
     if (busy) return;
     const found = bookById(id);
     if (!found || found.book.filler) return;
+    if (leaveForHub(found.book)) return;
     await openBookFlow(found.book, found.cat, el, { fromExpanded: false, asSpine: false });
   }
 
   async function onSpineClick(id, el, ev) {
     if (busy) return;
     const found = bookById(id);
-    if (!found) return;
-    if (found.book.filler || !found.book.cover) return;
+    if (!found || found.book.filler) return;
+    if (leaveForHub(found.book)) return;
+    if (!found.book.cover) return;
 
     const isTouch = ev && (ev.pointerType === "touch" || ("ontouchstart" in window && window.matchMedia("(hover: none)").matches));
 

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 leaves the shelf for `/bookshelf/<id>`
+ *   (本书). It does not open `posts[0]` and it does not play the flyer.
+ *   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. The flyer runs only when
+ *   a single-note book is extracted from the shelf and put back.
+ * - `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;
 };

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 opens `/bookshelf/<id>` and does not open the first note or play the extract 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. 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.3",
   "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"),