Pandoc EPUB输出中目录控制的优化与实现

在文档转换工具Pandoc的使用过程中，生成电子书格式EPUB时对目录结构的精确控制是一个常见需求。最新版本的Pandoc（3.2.1及以上）已经完善了对EPUB目录生成机制的支持，特别是通过.unlisted类和--toc-depth参数的控制方式。

EPUB目录的双重结构

EPUB格式包含两种目录结构：

1. 导航文档(nav.xhtml)：仅在用户指定--toc参数时生成
2. 必需目录文件(toc.ncx)：所有EPUB文件都必须包含的标准目录结构

目录控制的核心方法

1. 使用.unlisted类排除标题

在Markdown源文件中，为特定标题添加.unlisted类可以将其从生成的目录中排除，同时保持其在正文中的显示。这个特性现在已完全支持EPUB输出格式。

示例：

## 这个标题会出现在目录中
## 这个标题不会出现在目录中 {.unlisted}

2. 通过--toc-depth控制目录深度

--toc-depth参数允许用户精确控制目录包含的标题层级。例如，设置--toc-depth=1将只包含一级标题。

版本兼容性说明

值得注意的是，在Pandoc 3.1.2及更早版本中，目录控制功能可能存在一些限制。特别是：

• --toc-depth参数对某些标题层级的控制可能不完全生效
• .unlisted类在EPUB输出中的支持不够完善

建议用户升级到Pandoc 3.2.1或更高版本以获得完整的目录控制功能。新版本不仅修复了这些问题，还提供了更稳定一致的跨格式输出体验。

实际应用建议

对于需要同时输出PDF和EPUB格式的项目，现在可以使用相同的源文件和标记方式：

1. 使用.unlisted类控制特定标题的目录显示
2. 使用--toc-depth统一控制目录深度
3. 无需为不同输出格式准备不同的源文件或进行后期处理

这种统一的处理方式大大简化了多格式出版的工作流程，提高了文档维护的效率。