Hugo Book主题中主标题不在页面目录显示的解决方案

在Hugo Book主题的使用过程中，部分开发者发现文档中的一级标题（#标记）不会自动出现在右侧的页面目录（ToC）中。这种现象实际上是Hugo框架的默认行为，而非主题缺陷。

技术背景

Hugo的Markdown渲染引擎Goldmark默认配置中，Table of Contents的生成规则会跳过文档的根级标题。这种设计源于文档结构的常规实践——主标题通常作为页面标题显示在浏览器标签或页面顶部，因此不再重复出现在导航目录中。

配置方法

通过修改Hugo的配置文件可以调整目录生成行为。以下是关键配置参数说明：

1. markup.tableOfContents.startLevel：控制目录起始级别（默认值通常为2）
2. markup.tableOfContents.endLevel：控制目录结束级别
3. markup.tableOfContents.ordered：控制是否生成有序列表

实践建议

若确实需要将一级标题纳入目录，建议在项目配置文件中添加以下设置：

[markup.tableOfContents]
startLevel = 1
endLevel = 6

但需注意，这种配置可能导致：

• 页面标题在目录中重复出现
• 移动端浏览时导航栏可能显得冗长
• 破坏主题原有的视觉层次结构

最佳实践

对于大多数文档项目，推荐保持默认配置。可通过以下方式优化文档结构：

1. 将一级标题作为文档标题
2. 使用二级标题（##）开始内容章节
3. 保持标题层级的逻辑一致性
4. 利用主题提供的shortcode增强导航功能

这种结构既符合技术文档的通用规范，又能确保导航系统的清晰可用。