目录

文档目录可以通过各级标题自动生成,帮助用户快速浏览全文结构和定位章节。

对于一本技术手册而言,必须提供总目录(包含所有章节及附录)。如果是安装手册等还需要提供图目录、表目录。

发布在网页端的技术手册,两侧一般都配置有导航栏,包括全手册导航栏页内导航栏。这两种导航栏相当于技术手册的总目录单篇文档目录

如下是 PingCAP 技术文档站的目录实现:

../_images/table-of-contents.jpg

注意:

在实际操作中,文档右侧导航栏能显示哪些标题层级,由使用的文档框架决定。例如 Docusaurus 框架,虽然正文中对标题级别没有限制,但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###),一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。

因此,建议各公司根据使用的文档框架自定义文档的标题层级,如果右侧导航栏无法显示一级标题 (#),则可以自定义文档中的一级标题为 ##,二级标题为 ###,以此类推。