@windcoder/astro-theme-orchid 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@windcoder/astro-theme-orchid",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"description": "清新简约的 Astro 博客主题，以 Integration 形式提供，支持版本化升级与组件覆盖",
 	"type": "module",
 	"keywords": [

package/src/components/CategoryBar.astro

@@ -35,7 +35,7 @@ const isCategory = (name: string) =>
 			</a>
 			<a
 				class:list={["category-pill", { "is-active": isArchive }]}
-				href="/archive"
+				href="/archive/"
 			>
 				{t("archive")}
 			</a>

package/src/components/PostCard.astro

@@ -30,6 +30,11 @@ const { cover: rawCover, retries } = resolveCover(
    下）构建期解析为产物 URL，public / 外链原样直通 */
 const resolvedCover = rawCover ? await resolveSiteImage(rawCover) : rawCover;
 const cover = config.postList.showCover ? resolvedCover : null;
+/* §4.114：普通封面图失效的客户端兜底（api 文章 retries 末尾已含 fallbackCover，无需重复） */
+const coverFallback =
+	!retries && config.postList.fallbackCover
+		? await resolveSiteImage(config.postList.fallbackCover)
+		: "";
 /* §4.106：列表封面用缩略图（外链/未命中自动回退原图；点击进文章页看正文原图） */
 const thumb = cover ? getThumbInfo(cover) : null;
 const classes = [
@@ -59,6 +64,7 @@ const excerpt = d.excerpt || d.description;
           loading="lazy"
           data-lqip
           data-api-retries={retries ? JSON.stringify(retries) : undefined}
+          data-cover-fallback={coverFallback || undefined}
         />
       </a>
     )

package/src/routes/categories/[category]/[...page].astro

@@ -2,18 +2,19 @@
 import { getCollection } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
 import Pagination from "virtual:theme/components/Pagination.astro";
+import PostCard from "virtual:theme/components/PostCard.astro";
+import Sidebar from "virtual:theme/components/Sidebar.astro";
 import config from "virtual:theme/config";
 import { t } from "../../../i18n/index.js";
-import {
-	collectCategories,
-	formatDate,
-	getSortedPosts,
-} from "../../../utils.js";
+import { collectCategories, getSortedPosts } from "../../../utils.js";
+import { hydratePosts } from "../../_hydrate.js";
 
 /**
  * 分类详情（§4.87 分页）：每分类按 postList.pageSize 分页，第一页
- * /categories/<category>/（page 段省略），后续 /categories/<category>/2/ 起。
- * paginate() helper 生成 Page 对象（props.page），Page.data 即当前页文章。
+ * /categories/<category>/（page 段省略），后续 /categories/<category>/page/N/。
+ * 注意：分页段必须是 page/N/（§4.113）——Pagination 组件按此约定生成 href，
+ * paginate() 默认产出的 /N/ 会与组件链接错位导致 404，这里统一 remap。
+ * 布局与首页同构（§4.113）：PostCard 列表 + Sidebar，替代原单列窄卡片。
  */
 export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const all = await getCollection("posts", ({ data }) =>
@@ -24,30 +25,40 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	return [...collectCategories(sorted).entries()].flatMap(([category, posts]) =>
 		paginate(posts, {
 			params: { category },
-			props: { category },
+			props: { category, sorted },
 			pageSize: config.postList.pageSize,
-		}),
+		}).map((entry: any, i: number) => ({
+			params: { category, page: i > 0 ? `page/${i + 1}` : undefined },
+			props: entry.props,
+		})),
 	);
 }
 
-const { page, category } = Astro.props;
-const posts = page.data;
+const { page, category, sorted } = Astro.props;
+const pagePosts = await hydratePosts(page.data);
 ---
 
 <BaseLayout title={t('categoryTitle', { category })} page="categories">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{category}</h1>
-    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post: any) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">{formatDate(post.data.published)}</div>
-        </a>
-      ))
-    }
+  <div class="home-layout">
+    {/* 文章列表：与首页同一容器约定，供 app.ts 恢复与切换网格/列表形态 */}
+    <div
+      class="post-list"
+      id="postList"
+      data-allow-switch={config.postList.allowSwitch ? "true" : undefined}
+      data-default-layout={config.postList.defaultLayout}
+      data-grid-col={config.postList.gridColumnWidth}
+    >
+      <header class="archive-head reveal">
+        <h1 class="page-title">{category}</h1>
+        <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+      </header>
+      {
+        pagePosts.map((post: any) => (
+          <PostCard post={post} featured={post.data.pinned} />
+        ))
+      }
+      <Pagination page={page.currentPage} total={page.lastPage} basePath={`/categories/${category}/`} />
+    </div>
+    <Sidebar posts={sorted} />
   </div>
-  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/categories/${category}/`} />
 </BaseLayout>

package/src/routes/friends.astro

@@ -1,6 +1,7 @@
 ---
 import { getEntry, render } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import Comment from "virtual:theme/components/Comment.astro";
 import config from "virtual:theme/config";
 import { t } from "../i18n/index.js";
 import { resolveSiteImage } from "../utils/image.js";
@@ -88,4 +89,7 @@ const apply = config.friends.apply;
       </section>
     )
   }
+
+  <!-- §4.113：友链页评论区，支持直接留言申请友链（provider 未启用时自动 no-op） -->
+  <Comment path="/friends" />
 </BaseLayout>

package/src/routes/moments/[...page].astro

@@ -8,7 +8,9 @@ import { formatDate } from "../../utils.js";
 
 /**
  * 说说页（§4.87）：moments collection 时间流，按 published 新→旧，
- * 每页 20 条（第一页 /moments/，后续 /moments/2/）。
+ * 每页 20 条（第一页 /moments/，后续 /moments/page/N/）。
+ * 分页段必须是 page/N/（§4.113）——Pagination 组件按此约定生成 href，
+ * paginate() 默认产出的 /N/ 会与组件链接错位导致 404，这里统一 remap。
  * 正文走主题统一 markdown processor（全部增强语法可用）；配图 images 网格
  * 展示并接入通用灯箱（data-lightbox-group 组浏览）。
  */
@@ -19,7 +21,10 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const sorted = [...all].sort(
 		(a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
 	);
-	return paginate(sorted, { pageSize: 20 });
+	return paginate(sorted, { pageSize: 20 }).map((entry: any, i: number) => ({
+		params: { page: i > 0 ? `page/${i + 1}` : undefined },
+		props: entry.props,
+	}));
 }
 
 const { page } = Astro.props;

package/src/routes/posts/[...slug].astro

@@ -111,6 +111,11 @@ const { cover: rawArticleCover, retries: coverRetries } = resolveCover(
 const articleCover = rawArticleCover
 	? await resolveSiteImage(rawArticleCover)
 	: rawArticleCover;
+/* §4.114：普通封面图失效的客户端兜底（api 文章 retries 末尾已含 fallbackCover，无需重复） */
+const coverFallback =
+	!coverRetries && config.postList.fallbackCover
+		? await resolveSiteImage(config.postList.fallbackCover)
+		: "";
 const { Content, headings, remarkPluginFrontmatter } = await render(post);
 const { words, minutes } = remarkPluginFrontmatter as {
 	words?: number;
@@ -240,6 +245,7 @@ const jsonLd = {
           loading="eager"
           data-lqip
           data-api-retries={coverRetries ? JSON.stringify(coverRetries) : undefined}
+          data-cover-fallback={coverFallback || undefined}
         />
       </figure>
     )

package/src/routes/tags/[tag]/[...page].astro

@@ -2,13 +2,17 @@
 import { getCollection } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
 import Pagination from "virtual:theme/components/Pagination.astro";
+import PostCard from "virtual:theme/components/PostCard.astro";
+import Sidebar from "virtual:theme/components/Sidebar.astro";
 import config from "virtual:theme/config";
 import { t } from "../../../i18n/index.js";
-import { collectTags, formatDate, getSortedPosts } from "../../../utils.js";
+import { collectTags, getSortedPosts } from "../../../utils.js";
+import { hydratePosts } from "../../_hydrate.js";
 
 /**
  * 标签详情（§4.87 分页）：每标签按 postList.pageSize 分页，第一页
- * /tags/<tag>/（page 段省略），后续 /tags/<tag>/2/ 起。结构与分类详情页一致。
+ * /tags/<tag>/（page 段省略），后续 /tags/<tag>/page/N/。结构与分类详情页一致。
+ * 分页段 page/N/ 与布局同构改造见分类详情页注释（§4.113）。
  */
 export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const all = await getCollection("posts", ({ data }) =>
@@ -19,33 +23,40 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	return [...collectTags(sorted).entries()].flatMap(([tag, posts]) =>
 		paginate(posts, {
 			params: { tag },
-			props: { tag },
+			props: { tag, sorted },
 			pageSize: config.postList.pageSize,
-		}),
+		}).map((entry: any, i: number) => ({
+			params: { tag, page: i > 0 ? `page/${i + 1}` : undefined },
+			props: entry.props,
+		})),
 	);
 }
 
-const { page, tag } = Astro.props;
-const posts = page.data;
+const { page, tag, sorted } = Astro.props;
+const pagePosts = await hydratePosts(page.data);
 ---
 
 <BaseLayout title={t('tagTitle', { tag })} page="tags">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{tag}</h1>
-    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post: any) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">
-            {formatDate(post.data.published)}
-            {post.data.category ? ` · ${post.data.category}` : ''}
-          </div>
-        </a>
-      ))
-    }
+  <div class="home-layout">
+    {/* 文章列表：与首页同一容器约定，供 app.ts 恢复与切换网格/列表形态 */}
+    <div
+      class="post-list"
+      id="postList"
+      data-allow-switch={config.postList.allowSwitch ? "true" : undefined}
+      data-default-layout={config.postList.defaultLayout}
+      data-grid-col={config.postList.gridColumnWidth}
+    >
+      <header class="archive-head reveal">
+        <h1 class="page-title">{tag}</h1>
+        <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+      </header>
+      {
+        pagePosts.map((post: any) => (
+          <PostCard post={post} featured={post.data.pinned} />
+        ))
+      }
+      <Pagination page={page.currentPage} total={page.lastPage} basePath={`/tags/${tag}/`} />
+    </div>
+    <Sidebar posts={sorted} />
   </div>
-  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/tags/${tag}/`} />
 </BaseLayout>

package/src/schema.ts

@@ -368,9 +368,10 @@ export const themeConfigSchema = z.object({
 			fallbackCover: z.string().optional(),
 			/**
 			 * 随机封面图源（§4.33）：apis 非空时，frontmatter 显式 image:"api" 的文章
-			 * 从该列表取封面。URL 支持 {slug} 占位符（替换为文章 id），
+			 * 按 slug 确定性轮转选一条（§4.113，可传本地 public 路径列表做多源随机；
+			 * 单条时恒为第一条）。URL 支持 {slug} 占位符（替换为文章 id），
 			 * 并自动追加 ?v=<hash>（Java hashCode(slug)），同 slug 每次构建稳定同图。
-			 * 客户端加载失败时按列表顺序依次重试，全部失败显示本地 fallbackCover。
+			 * 客户端加载失败时按其余图源顺序依次重试，全部失败显示本地 fallbackCover。
 			 */
 			randomCover: z
 				.object({

package/src/scripts/app.ts

@@ -1110,8 +1110,9 @@ doc.addEventListener("click", (e) => {
 	}
 });
 
-/* 随机封面加载失败重试（§4.33）：img error 不冒泡，捕获阶段 document 级委托
-   （bundled 一次性执行，VT 换页后仍有效）。按 data-api-retries 顺序换源，
+/* 封面加载失败兜底（§4.33 随机重试 + §4.114 普通图兜底）：img error 不冒泡，捕获阶段
+   document 级委托（bundled 一次性执行，VT 换页后仍有效）。优先按 data-api-retries
+   顺序换源；无重试列表的普通封面图按 data-cover-fallback 换兜底图（仅试一次）；
    全部失败加 cover-broken 藏 img，露出底层 LQIP 渐变占位。 */
 doc.addEventListener(
 	"error",
@@ -1119,20 +1120,26 @@ doc.addEventListener(
 		const img = e.target as HTMLImageElement | null;
 		if (img?.tagName !== "IMG") return;
 		const raw = img.dataset.apiRetries;
-		if (!raw) return;
-		let list: string[] = [];
-		try {
-			list = JSON.parse(raw);
-		} catch {
-			return;
+		if (raw) {
+			try {
+				const list: string[] = JSON.parse(raw);
+				const idx = Number(img.dataset.retryIdx ?? "1");
+				if (idx >= 0 && idx < list.length) {
+					img.dataset.retryIdx = String(idx + 1);
+					img.src = list[idx];
+					return;
+				}
+			} catch {
+				/* 列表损坏则落到兜底分支 */
+			}
 		}
-		const idx = Number(img.dataset.retryIdx ?? "1");
-		if (idx >= 0 && idx < list.length) {
-			img.dataset.retryIdx = String(idx + 1);
-			img.src = list[idx];
-		} else {
-			img.classList.add("cover-broken");
+		const fb = img.dataset.coverFallback;
+		if (fb && !img.dataset.fallbackTried) {
+			img.dataset.fallbackTried = "1";
+			img.src = fb;
+			return;
 		}
+		if (raw || fb) img.classList.add("cover-broken");
 	},
 	true,
 );

package/src/utils.ts

@@ -212,8 +212,9 @@ export function randomCoverUrl(template: string, slug: string): string {
 
 /**
  * 解析文章封面（§4.33）：frontmatter image 为 "api" 且配置了图源时，
- * 返回 { cover, retries }——cover 为主图 URL，retries 为客户端
- * 加载失败时的依次重试列表（图源全量 + fallbackCover 兜底）。
+ * 返回 { cover, retries }——cover 按 slug 确定性轮转选一条（§4.113，
+ * 支持本地图片列表做多源随机；单图源退化为恒取第一条，行为不变），
+ * retries 为客户端加载失败时的依次重试列表（其余图源 + fallbackCover 兜底）。
  * 非 "api" 或未配置图源时原样返回，行为与之前一致。
  */
 export function resolveCover(
@@ -226,8 +227,9 @@ export function resolveCover(
 	if (image !== "api" || apis.length === 0) {
 		return { cover: image || firstImage || fallbackCover, retries: undefined };
 	}
-	const cover = randomCoverUrl(apis[0], slug);
-	const retries = [...apis.map((u) => randomCoverUrl(u, slug))];
+	const urls = apis.map((u) => randomCoverUrl(u, slug));
+	const idx = seedHash(slug) % urls.length;
+	const retries = [...urls.slice(idx + 1), ...urls.slice(0, idx)];
 	if (fallbackCover) retries.push(fallbackCover);
-	return { cover, retries };
+	return { cover: urls[idx], retries };
 }