hd-garden 0.9.1 → 0.9.3

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.1",
+  "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"),