@windcoder/astro-theme-orchid 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,53 @@
+---
+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 { getSortedPosts } from "../../utils.js";
+import { hydratePosts } from "../_hydrate.js";
+
+export async function getStaticPaths() {
+	const all = await getCollection("posts", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	// 置顶留在分页流内（§4.39）：与首页同一条 sorted 流切片，各页卡片数一致
+	const sorted = getSortedPosts(all);
+	const total = Math.max(
+		1,
+		Math.ceil(sorted.length / config.postList.pageSize),
+	);
+	// 第 1 页由 / 承担，这里生成 /page/2/ 起的分页
+	return Array.from({ length: total - 1 }, (_, i) => ({
+		params: { page: String(i + 2) },
+		props: { page: i + 2, total, posts: sorted },
+	}));
+}
+
+const { page, total, posts } = Astro.props;
+const pagePosts = await hydratePosts(
+	posts.slice(
+		(page - 1) * config.postList.pageSize,
+		page * config.postList.pageSize,
+	),
+);
+---
+
+<BaseLayout title={t('pageN', { n: page })} page="home">
+  <div class="home-layout">
+    {/* 文章列表（§4.34）：与首页同一容器约定，供 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}
+    >
+      {pagePosts.map((post) => <PostCard post={post} featured={post.data.pinned} />)}
+      <Pagination page={page} total={total} basePath="/" />
+    </div>
+    <Sidebar posts={posts} />
+  </div>
+</BaseLayout>

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

@@ -0,0 +1,350 @@
+---
+import { getCollection, render } from "astro:content";
+// KaTeX 样式：文章页独占加载（构建期渲染无客户端 JS，仅此一份 CSS）
+import "katex/dist/katex.min.css";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+// 分类导航栏（§4.23）：文章页主列顶部渲染（对齐首页 post-list 顶部位置，同列宽不全宽）
+import CategoryBar from "virtual:theme/components/CategoryBar.astro";
+import Comment from "virtual:theme/components/Comment.astro";
+import EncryptedContent from "virtual:theme/components/EncryptedContent.astro";
+import License from "virtual:theme/components/License.astro";
+import OutdatedCard from "virtual:theme/components/OutdatedCard.astro";
+import PostNav from "virtual:theme/components/PostNav.astro";
+import RecommendedPost from "virtual:theme/components/RecommendedPost.astro";
+import Sidebar from "virtual:theme/components/Sidebar.astro";
+import Toc from "virtual:theme/components/Toc.astro";
+import config from "virtual:theme/config";
+import { t } from "../../i18n/index.js";
+import { getLqipStyle } from "../../utils/lqip.js";
+import { getRelatedPosts } from "../../utils/related.js";
+import {
+	formatDate,
+	getSortedPosts,
+	resolveCover,
+	type SeriesEntry,
+	seriesEntries,
+} from "../../utils.js";
+
+export async function getStaticPaths() {
+	const all = await getCollection("posts", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	const sorted = getSortedPosts(all);
+
+	// 专题索引（§4.31→§4.75）：seriesEntries 分块规范化（未分组块最前、
+	// 各分组按组内首篇顺序排列、全局序号连续），与专题详情页共用同一规则
+	const seriesGroups = new Map<string, typeof sorted>();
+	for (const post of sorted) {
+		const name = post.data.series;
+		if (!name) continue;
+		const list = seriesGroups.get(name);
+		if (list) list.push(post);
+		else seriesGroups.set(name, [post]);
+	}
+	const seriesSorted = new Map<
+		string,
+		SeriesEntry<(typeof sorted)[number]>[]
+	>();
+	for (const [name, list] of seriesGroups) {
+		seriesSorted.set(name, seriesEntries(list));
+	}
+
+	// sorted 内 idx+1 为更早一篇（prev），idx-1 为更新一篇（next）
+	return sorted.map((post, idx) => {
+		// 专题导航（§4.31）：当前篇在专题内的位置 + 完整目录（含分块组头）
+		let seriesInfo: {
+			name: string;
+			total: number;
+			cur: number;
+			items: {
+				title: string;
+				id: string;
+				cur: boolean;
+				idx: number;
+				groupHead: string | null;
+			}[];
+		} | null = null;
+		const sName = post.data.series;
+		if (sName) {
+			const entries = seriesSorted.get(sName)!;
+			const sIdx = entries.findIndex((e) => e.post.id === post.id);
+			seriesInfo = {
+				name: sName,
+				total: entries.length,
+				cur: sIdx + 1,
+				items: entries.map((e) => ({
+					title: e.post.data.title,
+					id: e.post.id,
+					cur: e.index === sIdx,
+					idx: e.index + 1,
+					groupHead: e.groupHead,
+				})),
+			};
+		}
+		return {
+			params: { slug: post.id },
+			props: {
+				post,
+				prev: sorted[idx + 1] ?? null,
+				next: sorted[idx - 1] ?? null,
+				related: getRelatedPosts(sorted, post, config.relatedPosts.count),
+				// 文章页侧栏（P2）的聚合数据源
+				posts: sorted,
+				seriesInfo,
+			},
+		};
+	});
+}
+
+const { post, prev, next, related, posts, seriesInfo } = Astro.props;
+const d = post.data;
+/* 封面解析（§4.33）：image:"api" 时取确定性随机图；figure 与分享海报共用同一 URL */
+const { cover: articleCover, retries: coverRetries } = resolveCover(
+	d.image,
+	d.firstImage,
+	config.postList.fallbackCover,
+	config.postList.randomCover.apis,
+	post.id,
+);
+const { Content, headings, remarkPluginFrontmatter } = await render(post);
+const { words, minutes } = remarkPluginFrontmatter as {
+	words?: number;
+	minutes?: number;
+};
+
+const url = new URL(`/posts/${post.id}/`, Astro.site);
+// 支持卡（P2）：打赏入口 + 分享海报，二者均关闭则整卡不渲染；加密文章不渲染
+const showShareBtn = config.sharePoster.enabled && !d.password;
+const showSponsorBtn =
+	config.sponsor.showButtonInPost && config.pages.sponsor && !d.password;
+// 文章页侧栏（P2）：onPost 开启且非加密文章；侧栏内 toc widget 承担目录
+const postSidebar = config.sidebar.onPost && !d.password;
+
+// meta 区浏览量（§4.14，参考 orchid-blog）：复用评论系统 pageview 能力——
+// artalk/waline 由 SDK init 自动扫描填充对应选择器；twikoo 由 Twikoo.astro getCommentsCount 填充。
+// 条件：评论启用 + provider 支持计数 + 文章允许评论且未加密（评论不渲染时无数据来源）
+const c = config.comment;
+const pvProvider =
+	c.enabled && !d.password && d.comment
+		? (c.provider === "artalk" && c.artalk.visitorCount && "artalk") ||
+			(c.provider === "waline" && c.waline.visitorCount && "waline") ||
+			(c.provider === "twikoo" && c.twikoo.envId && "twikoo") ||
+			null
+		: null;
+const jsonLd = {
+	"@context": "https://schema.org",
+	"@type": "BlogPosting",
+	headline: d.title,
+	description: d.description,
+	datePublished: d.published.toISOString(),
+	dateModified: (d.updated ?? d.published).toISOString(),
+	wordCount: words,
+	keywords: d.tags.join(", "),
+	author: { "@type": "Person", name: d.author || config.author },
+	mainEntityOfPage: url.href,
+};
+---
+
+<BaseLayout title={d.title} description={d.description} keywords={d.tags} page="post" ogImage={config.og.enabled ? `/og/${post.id}.png` : undefined}>
+  {/* 左右两栏布局（对齐参考模板）：标题/封面/正文/许可/上下篇/支持卡/推荐/评论全部收进正文列，
+      侧栏（或 TOC）独占右列；≤767px 退化为单列堆叠 */}
+  <div class="post-layout">
+    {/* 阅读进度条（§4.12）：仅文章页渲染，app.ts 滚动驱动 scaleX */}
+    <div class="read-progress" id="readProgress" aria-hidden="true"></div>
+    <div class="post-main">
+    {/* 分类导航栏（§4.23）：主列顶部，与首页 post-list 顶部位置对等；enabled 关闭时组件自不渲染 */}
+    <CategoryBar />
+  <header class="post-header reveal">
+    <h1 class="post-title-lg" data-pagefind-body data-pagefind-weight="10" data-pagefind-meta="title">{d.title}</h1>
+    {/* meta 区图标化（§4.14，参考 orchid-blog PostMeta）：flex-wrap 自动换行适配窄屏 */}
+    <div class="post-meta meta-icons">
+      <span class="meta-item">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4"/><path d="M8 2v4"/><path d="M3 10h18"/></svg>
+        <time datetime={d.published.toISOString()}>{formatDate(d.published)}</time>
+      </span>
+      {d.updated && (
+        <span class="meta-item">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12a9 9 0 1 1-2.64-6.36"/><path d="M21 3v6h-6"/></svg>
+          <time datetime={d.updated.toISOString()}>{formatDate(d.updated)}</time>
+        </span>
+      )}
+      {/* 分类/标签内联（§4.22，对齐 orchid-blog PostMeta）：跟随日期，不再分列标题上下 */}
+      {d.category && (
+        <span class="meta-item">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></svg>
+          <a href={`/categories/${encodeURIComponent(d.category)}/`}>{d.category}</a>
+        </span>
+      )}
+      {d.tags.length > 0 && (
+        <span class="meta-item meta-tags-item">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12.586 2.586A2 2 0 0 0 11.172 2H4a2 2 0 0 0-2 2v7.172a2 2 0 0 0 .586 1.414l8.704 8.704a2.426 2.426 0 0 0 3.42 0l6.58-6.58a2.426 2.426 0 0 0 0-3.42z"/><circle cx="7.5" cy="7.5" r=".5" fill="currentColor"/></svg>
+          {d.tags.map((tag, i) => (
+            <>
+              {i > 0 && <span class="tag-sep" aria-hidden="true">/</span>}
+              <a href={`/tags/${encodeURIComponent(tag)}/`}>{tag}</a>
+            </>
+          ))}
+        </span>
+      )}
+      {words ? (
+        <span class="meta-item">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M16 13H8"/><path d="M16 17H8"/></svg>
+          {t('wordsCount', { n: words })}
+        </span>
+      ) : null}
+      {minutes ? (
+        <span class="meta-item">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg>
+          {t('minutesCount', { n: minutes })}
+        </span>
+      ) : null}
+      {d.pinned && (
+        <span class="meta-item pin-flag">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 17v5"/><path d="M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z"/></svg>
+          {t('pinned')}
+        </span>
+      )}
+      {d.password && (
+        <span class="meta-item enc-flag">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="11" width="18" height="11" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg>
+          {t('postEncrypted')}
+        </span>
+      )}
+      {pvProvider && (
+        <span class="meta-item meta-pv" aria-label={t('pageviews')}>
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.06 12.35a1 1 0 0 1 0-.7 10.75 10.75 0 0 1 19.88 0 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-19.88 0"/><circle cx="12" cy="12" r="3"/></svg>
+          {pvProvider === 'artalk' && <span class="artalk-pv-count" data-path={`/posts/${post.id}`}>1</span>}
+          {pvProvider === 'waline' && <span class="waline-pageview-count" data-path={`/posts/${post.id}`}>1</span>}
+          {pvProvider === 'twikoo' && <span id="twikoo_visitors" data-path={`/posts/${post.id}`}>1</span>}
+        </span>
+      )}
+    </div>
+  </header>
+  {/* 灯箱组容器（§4.71）：封面 + 专题导航 + 正文整体归组，封面成为组内第 0 张——
+      点击封面/正文任一图都可切换全组；纯归组标记无样式（.post-main 为块流，包装层零副作用）。
+      内部子元素不得再带组属性（嵌套容器双绑定，§4.70 契约），故 figure 去 data-lightbox、
+      article 去 data-lightbox-gallery。wrapper 不入 pagefind 索引（索引点在 article） */}
+  <div data-lightbox-gallery>
+  {
+    articleCover && (
+      <figure class="article-cover reveal">
+        <div class="qy-lqip" style={getLqipStyle(articleCover)} aria-hidden="true"></div>
+        <img
+          src={articleCover}
+          alt={d.title}
+          loading="eager"
+          data-lqip
+          data-api-retries={coverRetries ? JSON.stringify(coverRetries) : undefined}
+        />
+      </figure>
+    )
+  }
+  {/* 专题导航卡（§4.31）：正文之前出专题目录，当前篇高亮不可点 */}
+  {
+    seriesInfo && (
+      <nav class="series-nav card reveal" aria-label={t('seriesCatalog')}>
+        <div class="series-nav-head">
+          <span class="series-nav-title">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m19 21-7-4-7 4V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2v16z"/></svg>
+            {seriesInfo.name}
+          </span>
+          <span class="series-nav-progress">
+            <a href={`/series/${encodeURIComponent(seriesInfo.name)}/`}>{t('seriesCatalog')}</a>
+            <span class="series-nav-count">{t('seriesProgress', { cur: seriesInfo.cur, total: seriesInfo.total })}</span>
+          </span>
+        </div>
+        <ol class="series-nav-list">
+          {seriesInfo.items.map((item) => (
+            <>
+              {item.groupHead && <li class="series-nav-group" aria-hidden="true">{item.groupHead}</li>}
+              <li class:list={["series-nav-item", { cur: item.cur }]}>
+                {item.cur ? (
+                  <span class="series-nav-row">
+                    <span class="series-nav-idx">{item.idx}</span>
+                    <span class="series-nav-label">{item.title}</span>
+                  </span>
+                ) : (
+                  <a class="series-nav-row" href={`/posts/${item.id}/`}>
+                    <span class="series-nav-idx">{item.idx}</span>
+                    <span class="series-nav-label">{item.title}</span>
+                  </a>
+                )}
+              </li>
+            </>
+          ))}
+        </ol>
+      </nav>
+    )
+  }
+    {/* data-pagefind-body（M3b-b6）：限定 Pagefind 只索引标题与正文（h1 在 article 外，双 body 标记） */}
+    <article class="prose reveal" data-pagefind-body>
+      {d.password ? (
+        /* 加密文章（M3b-b7）：构建期把正文渲染后整体加密，页面只出密文 + 锁 UI；
+           TOC 的 headings 来自构建期明文解析，会在锁旁泄漏标题结构，故一并隐藏 */
+        <EncryptedContent password={d.password} slug={post.id} hint={d.passwordHint}>
+          <Content />
+        </EncryptedContent>
+      ) : (
+        <Content />
+      )}
+    </article>
+  </div>
+    {/* 过时提醒（§4.11）：许可卡之前展示；加密文章不渲染 */}
+    {!d.password && <OutdatedCard updated={d.updated ?? d.published} published={d.published} />}
+    <License licenseName={d.licenseName} licenseUrl={d.licenseUrl} enabled={d.license} />
+    <PostNav prev={prev ?? undefined} next={next ?? undefined} />
+  {/* 支持卡（P2）：打赏入口 + 分享海报（share-poster.ts 仍按 #qy-share-btn 与 data-* 绑定） */}
+  {
+    (showSponsorBtn || showShareBtn) && (
+      <div class="support-card reveal">
+        <div class="support-info">
+          <h3>{t('supportTitle')}</h3>
+          <p>{t('supportDesc')}</p>
+        </div>
+        <div class="support-actions">
+          {showSponsorBtn && (
+            <a class="btn-sponsor" href="/sponsor/">
+              <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"></path></svg>
+              {t('sponsorMe')}
+            </a>
+          )}
+          {showShareBtn && (
+            <button
+              type="button"
+              id="qy-share-btn"
+              class="btn-poster"
+              data-title={d.title}
+              data-author={d.author || config.author || config.title}
+              data-desc={d.description}
+              data-date={d.published.toISOString()}
+              data-cover={articleCover ?? ''}
+              data-url={url.href}
+              data-site={config.title}
+            >
+              <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="18" cy="5" r="3"></circle><circle cx="6" cy="12" r="3"></circle><circle cx="18" cy="19" r="3"></circle><line x1="8.59" y1="13.51" x2="15.42" y2="17.49"></line><line x1="15.41" y1="6.51" x2="8.59" y2="10.49"></line></svg>
+              {t('sharePoster')}
+            </button>
+          )}
+        </div>
+      </div>
+    )
+  }
+  {/* 相关/随机文章推荐（P1-12）：相关栏构建期评分，随机栏客户端抽取；候选均已排除加密文章 */}
+  {
+    config.relatedPosts.enabled && (
+      <RecommendedPost related={related} currentId={post.id} randomCount={config.relatedPosts.randomCount} />
+    )
+  }
+  {/* 加密文章不渲染评论（评论内容依赖正文上下文，明文评论区会破坏加密语义） */}
+  <Comment path={`/posts/${post.id}`} enabled={d.comment && !d.password} title={d.title} />
+    </div>
+    {/* 侧栏开关（P2）：onPost 时侧栏进右列，TOC 由侧栏 toc widget 承担；
+        关闭侧栏时 TOC 保持正文右侧原位 */}
+    {postSidebar ? (
+      <Sidebar posts={posts} variant="post" headings={headings} currentId={post.id} />
+    ) : (
+      config.toc.enabled && !d.password && <Toc headings={headings} />
+    )}
+  </div>
+  <script is:inline type="application/ld+json" set:html={JSON.stringify(jsonLd)} />
+</BaseLayout>

package/src/routes/robots.txt.ts

@@ -0,0 +1,18 @@
+import type { APIRoute } from "astro";
+
+export const GET: APIRoute = ({ site }) => {
+	// §4.63：sitemap 改由官方 @astrojs/sitemap 产出，入口为 sitemap-index.xml
+	const sitemap = site
+		? new URL("sitemap-index.xml", site).href
+		: "https://blog.example.com/sitemap-index.xml";
+	const body = [
+		"User-agent: *",
+		"Allow: /",
+		"",
+		`Sitemap: ${sitemap}`,
+		"",
+	].join("\n");
+	return new Response(body, {
+		headers: { "Content-Type": "text/plain; charset=utf-8" },
+	});
+};

package/src/routes/rss.xml.ts

@@ -0,0 +1,37 @@
+import { getCollection } from "astro:content";
+import config from "virtual:theme/config";
+import rss from "@astrojs/rss";
+import type { APIContext, APIRoute } from "astro";
+import { getSortedPosts } from "../utils.js";
+
+/**
+ * RSS（§4.63 官方 @astrojs/rss 端点）：item description 使用 frontmatter
+ * description，不做全文输出（避免 RSS 端点再渲染全部 Markdown）。
+ * channel 头部、atom:link self、XML 转义由官方库负责；trailingSlash 与
+ * 主题 trailingSlash: "always" 口径一致（/posts/xxx/）。
+ */
+export const GET: APIRoute = async (context: APIContext) => {
+	const all = await getCollection("posts", ({ data }) => !data.draft);
+	const posts = getSortedPosts(all).slice(0, 20);
+	const site = context.site ?? new URL("https://blog.example.com");
+
+	return rss({
+		title: config.title,
+		description: config.description,
+		site,
+		items: posts.map((post) => ({
+			title: post.data.title,
+			description: post.data.description,
+			link: `/posts/${post.id}/`,
+			pubDate: post.data.published,
+		})),
+		// atom 命名空间 + feed 自引用（v4 不再自动生成，保持对原手写版的兼容）
+		xmlns: { atom: "http://www.w3.org/2005/Atom" },
+		// RSS <language> 通道级语言标记（跟随站点语言）
+		customData: [
+			`<language>${config.lang}</language>`,
+			`<atom:link href="${new URL("rss.xml", site).href}" rel="self" type="application/rss+xml" />`,
+		].join(""),
+		trailingSlash: true,
+	});
+};

package/src/routes/series/[name].astro

@@ -0,0 +1,66 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import { t } from "../../i18n/index.js";
+import { formatDate, type PostLike, seriesEntries } from "../../utils.js";
+import { hydratePosts } from "../_hydrate.js";
+
+// 专题详情页（§4.31→§4.75）：seriesEntries 分块规范化——
+// 未分组文章块最前，各分组按组内首篇顺序排列，全局序号连续
+export async function getStaticPaths() {
+	const all = await getCollection("posts", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	const posts = await hydratePosts(all);
+
+	const groups = new Map<string, PostLike[]>();
+	for (const post of posts) {
+		const name = post.data.series;
+		if (!name) continue;
+		const list = groups.get(name);
+		if (list) list.push(post);
+		else groups.set(name, [post]);
+	}
+
+	return [...groups.entries()].map(([name, list]) => ({
+		params: { name },
+		props: { name, entries: seriesEntries(list) },
+	}));
+}
+
+const { name, entries } = Astro.props as {
+	name: string;
+	entries: ReturnType<typeof seriesEntries>;
+};
+const posts = entries.map((e) => e.post);
+const latest = posts.reduce(
+	(max, p) => (p.data.published > max ? p.data.published : max),
+	posts[0]!.data.published,
+);
+---
+
+<BaseLayout title={name} page="series">
+  <header class="archive-head reveal">
+    <p class="page-sub series-crumb"><a href="/series/">{t('series')}</a></p>
+    <h1 class="page-title">{name}</h1>
+    <p class="page-sub">
+      {t('totalPosts', { n: posts.length })} · {t('seriesUpdated', { date: formatDate(latest) })}
+    </p>
+  </header>
+  <ol class="series-list">
+    {
+      entries.map((entry) => (
+        <>
+          {entry.groupHead && <li class="series-group-title" aria-hidden="true">{entry.groupHead}</li>}
+          <li class="series-item reveal">
+            <a class="series-link card" href={`/posts/${entry.post.id}/`}>
+              <span class="series-idx">{entry.index + 1}</span>
+              <span class="series-title">{entry.post.data.title}</span>
+              <span class="series-date">{formatDate(entry.post.data.published)}</span>
+            </a>
+          </li>
+        </>
+      ))
+    }
+  </ol>
+</BaseLayout>

package/src/routes/series/index.astro

@@ -0,0 +1,64 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import { t } from "../../i18n/index.js";
+import { formatDate, type PostLike } from "../../utils.js";
+import { hydratePosts } from "../_hydrate.js";
+
+// 专题聚合页（§4.31）：frontmatter series 非空即成组，按组内最新发布倒序
+const all = await getCollection("posts", ({ data }) =>
+	import.meta.env.PROD ? !data.draft : true,
+);
+const posts = await hydratePosts(all);
+
+interface SeriesGroup {
+	name: string;
+	list: PostLike[];
+	latest: Date;
+}
+
+const groups = new Map<string, PostLike[]>();
+for (const post of posts) {
+	const name = post.data.series;
+	if (!name) continue;
+	const list = groups.get(name);
+	if (list) list.push(post);
+	else groups.set(name, [post]);
+}
+
+const seriesList: SeriesGroup[] = [...groups.entries()]
+	.map(([name, list]) => ({
+		name,
+		list,
+		latest: list.reduce(
+			(max, p) => (p.data.published > max ? p.data.published : max),
+			list[0]!.data.published,
+		),
+	}))
+	.sort((a, b) => b.latest.getTime() - a.latest.getTime());
+---
+
+<BaseLayout title={t('series')} page="series">
+  <header class="archive-head reveal">
+    <h1 class="page-title">{t('series')}</h1>
+    <p class="page-sub">{t('seriesTotal', { n: seriesList.length })}</p>
+  </header>
+  {
+    seriesList.length === 0 ? (
+      <p class="series-empty card reveal">{t('seriesEmpty')}</p>
+    ) : (
+      <div class="series-grid">
+        {seriesList.map((s) => (
+          <a class="series-card card reveal" href={`/series/${encodeURIComponent(s.name)}/`}>
+            <h2 class="series-name">{s.name}</h2>
+            <p class="series-meta">
+              <span>{t('seriesPostsCount', { n: s.list.length })}</span>
+              <span>·</span>
+              <span>{t('seriesUpdated', { date: formatDate(s.latest) })}</span>
+            </p>
+          </a>
+        ))}
+      </div>
+    )
+  }
+</BaseLayout>