必须用包裹目录，内含带唯一id的h2-h4标题及ol/ul列表，锚点链接需匹配文件路径与层级结构，否则EPUB阅读器无法正确解析导航。
用 <nav></nav> 包住目录，别用 <div> 或 <code><section></section>
屏幕阅读器和电子书阅读器（如 Kindle、Apple Books）依赖语义化标签识别导航区域。<nav></nav> 是唯一被广泛支持的导航容器，换成 <div class="toc"> 会导致跳转失败或目录不可见。
<ul>
<li>必须把整个目录结构（含标题、链接列表）放在 <code><nav></nav> 内，且建议加 aria-label="Table of Contents"
<nav></nav>——一章一个 <nav></nav> 就够了，多层导航反而干扰解析<nav></nav> 的子元素语义，所以 <ol></ol> 或 <ul></ul> 必须显式存在，不能只靠 CSS 生成序号
id 值必须全局唯一，且不能含空格或特殊字符
章节跳转靠的是 href="#chapter-2" 这种锚点，一旦 id="Chapter 2" 或 id="ch2"（重复）就会断链。EPUB 打包工具（如 ebook-convert）通常不校验 ID 冲突，但阅读器运行时直接失效。
- 推荐格式：
id="ch02-introduction"（小写、短横线、无中文、无下划线开头） - 所有章节标题的
<h2></h2>或<h3></h3>必须带id，否则目录项无法定位 - 避免用自动生成 ID（如 Markdown 转 HTML 产生的
id="introduction-1"），它可能在多次编译后变化，导致 EPUB 内部链接失效
层级必须严格对应 <h2></h2>→<h3></h3>→<h4></h4>，不能跳级
EPUB 的 NCX 和 newer NAV document 都按标题层级推导大纲树。如果目录里显示“2.1.1”，但 HTML 中是 <h2></h2> 后直接 <h4></h4>，阅读器会忽略该节点或打乱顺序。
- 目录项顺序 = 页面中
<h2></h2>、<h3></h3>、<h4></h4>出现的先后顺序，不是靠 CSS 或 JS 排列 - 不要用
<h1></h1>做章节标题——它通常留给书名，多数阅读器禁止在内容页使用<h1></h1>作为节标题 - 如果某章没有二级标题，就别在目录里硬加“2.1”；空白层级会让 EPUB 校验失败（如
epubcheck报ERROR(RSC-005)）
锚点链接必须指向同一 HTML 文件内的 id，跨文件需用相对路径
EPUB 是 ZIP 包，每个章节通常是独立 HTML 文件（如 chapter2.xhtml）。目录页（toc.xhtml）里的链接不能只写 #sec-3，否则永远跳不到其他文件。
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。
立即学习“前端免费学习笔记（深入）”；
- 同文件内跳转：
<a href="#sec-3">第三节</a> - 跨文件跳转：
<a href="chapter2.xhtml#sec-3">第二章第三节</a>（路径必须小写、无空格、带扩展名） - 绝对路径（
/Text/chapter2.xhtml）在大多数阅读器上无效，只认相对路径 - 某些工具（如 Pandoc）默认生成跨文件相对路径，但若手动移动文件未同步更新链接，
ebook-convert不报错，却会在 Kindle 上显示“无法打开页面”
最常被忽略的是：EPUB 的 TOC 不是纯前端行为，它依赖 HTML 结构 + 正确路径 + 严格层级三者同时成立。少一个，阅读器就可能当没这回事。
