在 reStructuredText 中将目录标题显示为标题（或完全隐藏）

Question

我正在编辑的 reStructuredText (.rst) 文档需要 table 的内容，所以我添加了

.. contents:: Table of Contents

在合适的地方，效果很好。

问题是，至少在 GitHub 的 RST parser/renderer/whatever 中，"Table of Contents" 标题显示正常，non-header 文本会，当我想要一个关卡时改为 2 标题。

Here's the README.rst file我在努力改变。请注意 "Table of Contents" 看起来不太像一个部分 header 或标题。

有没有办法

1. 将 TOC 标题设置为 2 级标题，或

2. 完全禁用 TOC 标题，这样我就可以添加自己的标题了吗？ （类似于以下内容）

   Table of Contents
   -----------------
   .. contents:: :disable_title: true
   

Answer 1

您可以通过组合 :local: option 和省略目录标题来禁用目录标题：

Your h2 level title here
------------------------
.. contents::
   :local:

但请注意，本地选项 将 TOC 本地化为仅列出其所在部分的子部分，而不是列出文档中的每个部分。如果您仍想包含所有内容，请制作 top-level header 并将目录直接放在其下方。但是，这仍然会排除 top-level header 本身。