目录
====================


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

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

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

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

.. image:: ../media/table-of-contents.jpg

注意：

在实际操作中，文档右侧导航栏能显示哪些 `标题层级 <../文档结构样式/标题.html#标题的层级>`_，由使用的文档框架决定。例如 `Docusaurus 框架 <https://docusaurus.io/docs/en/navigation>`_，虽然正文中对标题级别没有限制，但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###)，一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。

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