Display TOC title as a heading (or hide it altogether) in reStructuredText

Question

I needed a table of contents for a reStructuredText (.rst) document I was editing, so I added

.. contents:: Table of Contents

in the appropriate place and it works fine.

Problem is, at least in GitHub's RST parser/renderer/whatever, the "Table of Contents" title displays just like normal, non-header text would, when I want a level 2-heading instead.

Here's the README.rst file I'm trying to change. Notice how "Table of Contents" looks not so much like a section header or title.

Is there a way to either

1. style the TOC title like a level 2-heading, or

2. disable the TOC title altogether, so I could just add my own? (something like the following)

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

Answer 1

You can disable the TOC title by combining the :local: option with omission of the TOC title:

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

But note that the local option localizes the TOC to only list subsections of the section in which it is placed rather than listing every section in the document. If you still want to include everything, make a top-level header and place the TOC directly beneath it. This will still exclude the top-level header itself, however.