feat(epub): 保留 sidebar 层级并生成嵌套目录

- 线性目录会丢失分组关系，导致阅读器内导航语义不清晰
- 复用 sidebar 树同时生成 toc.xhtml 与 nav.xhtml，避免目录来源分叉
- 调整目录页样式以突出顶级层级，并弱化不可点击的分组标题

Author: jinzhongjia

course/.vitepress/epub/build.ts

@@ -13,7 +13,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { config } from "./config.ts";
-import { resolveChapters } from "./sidebar.ts";
+import { resolveChapters, buildNavTree } from "./sidebar.ts";
 import { preprocess } from "./preprocess.ts";
 import { rewriteLinksAndImages } from "./links.ts";
 import { ImageCollector, toPng } from "./images.ts";
@@ -26,8 +26,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 async function main() {
   console.log(`[epub] 开始构建《${config.title}》`);
 
-  // 1. 解析章节
+  // 1. 解析章节 + 构建层级目录树
   const { chapters, routeToFile } = resolveChapters(config);
+  const navTree = buildNavTree(routeToFile);
   console.log(`[epub] 共 ${chapters.length} 个章节`);
 
   // 2. 准备渲染器与图片收集器
@@ -83,6 +84,7 @@ async function main() {
   const epub = await packageEpub({
     config,
     chapters,
+    navTree,
     renderedChapters: rendered,
     images: imageMap,
     fonts,

course/.vitepress/epub/package.ts

@@ -1,6 +1,6 @@
 import JSZip from "jszip";
 import type { EpubConfig } from "./config.ts";
-import type { Chapter } from "./sidebar.ts";
+import type { Chapter, NavNode } from "./sidebar.ts";
 import { escapeXml, wrapXhtml } from "./render.ts";
 
 export interface RenderedChapter {
@@ -12,6 +12,8 @@ export interface RenderedChapter {
 export interface PackageInput {
   config: EpubConfig;
   chapters: Chapter[];
+  /** 层级目录树（保留 sidebar 父/子结构） */
+  navTree: NavNode[];
   renderedChapters: RenderedChapter[];
   /** epubPath(去掉 ../) -> bytes，统一 PNG */
   images: Map<string, Uint8Array>;
@@ -31,9 +33,34 @@ function mimeOf(p: string): string {
   return "application/octet-stream";
 }
 
+/**
+ * 递归渲染层级目录为嵌套列表。
+ * - 有 href 的节点 -> <a>；分组节点 -> <span>（EPUB nav 允许，用于不可点击的层级标题）；
+ * - 子节点嵌套在父 <li> 内的子列表中。
+ * @param tag nav.xhtml 必须用 ol；可见目录页用 ul 便于样式化
+ */
+function renderNavTree(
+  nodes: NavNode[],
+  hrefPrefix: string,
+  tag: "ol" | "ul",
+): string {
+  const items = nodes
+    .map((n) => {
+      const head = n.href
+        ? `<a href="${hrefPrefix}${n.href}">${escapeXml(n.text)}</a>`
+        : `<span>${escapeXml(n.text)}</span>`;
+      const sub = n.children.length
+        ? `\n${renderNavTree(n.children, hrefPrefix, tag)}\n`
+        : "";
+      return `<li>${head}${sub}</li>`;
+    })
+    .join("\n");
+  return `<${tag}>\n${items}\n</${tag}>`;
+}
+
 /** 组装并生成 EPUB3 二进制 */
 export async function packageEpub(input: PackageInput): Promise<Uint8Array> {
-  const { config, chapters, renderedChapters, images, fonts, css, cover } =
+  const { config, navTree, renderedChapters, images, fonts, css, cover } =
     input;
   const lang = config.language;
   const bookId = "urn:uuid:" + crypto.randomUUID();
@@ -64,15 +91,10 @@ export async function packageEpub(input: PackageInput): Promise<Uint8Array> {
     `<div class="cover"><img src="../images/cover.png" alt="封面"/></div>`,
     lang,
   );
-  const tocItems = chapters
-    .map(
-      (ch) =>
-        `<li class="toc-l${Math.min(ch.item.level, 2)}"><a href="${ch.fileName}">${escapeXml(ch.item.text)}</a></li>`,
-    )
-    .join("\n");
+  // 目录页：保留 sidebar 的父/子层级（嵌套 ul）。toc.xhtml 与章节同在 text/ 目录，故无路径前缀
   const tocXhtml = wrapXhtml(
     "目录",
-    `<div class="toc-page"><h1>目录</h1><ul class="toc-list">\n${tocItems}\n</ul></div>`,
+    `<div class="toc-page"><h1>目录</h1>\n${renderNavTree(navTree, "", "ul")}\n</div>`,
     lang,
   );
 
@@ -142,13 +164,7 @@ export async function packageEpub(input: PackageInput): Promise<Uint8Array> {
 </package>`;
   oebps.file("content.opf", opf);
 
-  // ---- nav.xhtml ----
-  const navList = chapters
-    .map(
-      (ch) =>
-        `<li><a href="text/${ch.fileName}">${escapeXml(ch.item.text)}</a></li>`,
-    )
-    .join("\n      ");
+  // ---- nav.xhtml ----（nav.xhtml 在 OEBPS/ 下，章节在 text/，故前缀 text/）
   oebps.file(
     "nav.xhtml",
     `<?xml version="1.0" encoding="UTF-8"?>
@@ -158,9 +174,7 @@ export async function packageEpub(input: PackageInput): Promise<Uint8Array> {
 <body>
   <nav epub:type="toc" id="toc">
     <h1>目录</h1>
-    <ol>
-      ${navList}
-    </ol>
+${renderNavTree(navTree, "text/", "ol")}
   </nav>
 </body>
 </html>`,

course/.vitepress/epub/sidebar.ts

@@ -84,3 +84,35 @@ export function resolveChapters(config: EpubConfig): {
 
   return { chapters, routeToFile };
 }
+
+/** 层级目录节点：保留 sidebar 的父/子结构用于生成嵌套 TOC */
+export interface NavNode {
+  text: string;
+  /** 对应章节的 xhtml 文件名；分组节点（无可解析链接）则为空 */
+  href?: string;
+  children: NavNode[];
+}
+
+/**
+ * 按 sidebar 原始树构建层级目录。
+ * - 有 link 且能解析到章节的节点 -> 带 href 的可点击项；
+ * - 分组节点（仅有 items、无 link）-> 无 href 的标题项，其下嵌套子节点；
+ * - 既无法链接又无子节点的空节点跳过。
+ */
+export function buildNavTree(routeToFile: Record<string, string>): NavNode[] {
+  const conv = (nodes: SidebarNode[]): NavNode[] => {
+    const out: NavNode[] = [];
+    for (const node of nodes) {
+      const children = node.items ? conv(node.items) : [];
+      let href: string | undefined;
+      if (node.link) {
+        const route = normalizeRouteKey(node.link);
+        href = routeToFile[route] || routeToFile[route + "/"];
+      }
+      if (!href && children.length === 0) continue;
+      out.push({ text: node.text, href, children });
+    }
+    return out;
+  };
+  return conv(sidebar as unknown as SidebarNode[]);
+}

course/.vitepress/epub/style.css

@@ -216,25 +216,27 @@ img {
   max-width: 100%;
 }
 
-/* 目录页 */
+/* 目录页（嵌套层级） */
 .toc-page h1 {
   text-align: center;
 }
-.toc-list {
+.toc-page ul {
   list-style: none;
+  padding-left: 1.2em;
+}
+.toc-page > ul {
   padding-left: 0;
 }
-.toc-list li {
+.toc-page li {
   margin: 0.35em 0;
 }
-.toc-list .toc-l0 {
+/* 顶级条目（分组/一级章节）加粗 */
+.toc-page > ul > li > a,
+.toc-page > ul > li > span {
   font-weight: 700;
   font-size: 1.05em;
 }
-.toc-list .toc-l1 {
-  padding-left: 1.2em;
-}
-.toc-list .toc-l2 {
-  padding-left: 2.4em;
-  font-size: 0.95em;
+/* 分组标题（无链接）用 span，弱化为非链接色 */
+.toc-page span {
+  color: #555;
 }