Search code examples
python-sphinxrestructuredtext

Include contents directive without changing headers to links

If I include a .. contents:: directive in a document all of the headings on the page become links to page anchors #id1, #id2...

Without .. contents::, the headers on the page are not links (but do show the anchor link on hover). Is it possible to include the contents without changing the headings on the page to links?

.. contents:: Table of Contents

#############
Heading 1
#############

*************
Heading 2
*************

Example with contents and links

Example without contents and no links

Solution

  • The contents directive accepts a few options, one of them is backlinks. Its default value is entry, which adds links from each heading back to its corresponding entry in the table of contents. This is the behavior you observe. With top, it would link back to the table of contents as a whole. If you set the value to none, the back-links are removed.

    .. contents:: Table of Contents
   :backlinks: none

#############
Heading 1
#############

*************
Heading 2
*************

    Here is the live rendering provided by rst.ninjs.org, same site you linked to. Note that it renders the reStructuredText input with Docutils. The section links that show on hover are added by Sphinx. At least by default. You can suppress them too by setting html_permalinks = False in Sphinx's configuration file conf.py.