contents ¶

The contents directive searches the current document for section and generates local table of contents at the place where used. The directive may appear anywhere but usually is at the top of the document.

Global and local ToC ¶

Is contents what you really looking for? The directive’s main purpose is to print a document’s ToC in the document body, but many Sphinx themes has “on this page” sidebar that shows current document’s ToC automatically.

If you want table of contents of the whole documentation (not the current document), see toctree.

Local ToC with backlinks ¶

In its simplest form, the contents directive generates local ToC where items are links to the particular section, and the default title text for your language (“Contents” in English).

.. contents::

Explicit title ¶

To change a title, pass custom text as a directive argument right after contents:: (note the space after ::).

.. contents:: Local table of contents

Section depth ¶

The number of section levels to be printed. The default is unlimited depth (all section levels).

.. contents::
   :depth: 2

Sample section ¶

To show how ¶

contents directive ¶

works with section levels ¶

Disable backlinks ¶

By default, contents turns sections into links pointing to the local ToC (thus the name “backlinks”). With :backlinks: none option, you can turn this off.

Important

Some Sphinx themes add backlinks automatically to all section headers, so the following example will not work.

:orphan:

##########################
Contents without backlinks
##########################

Testing ``contents::`` directive without backlinks.

.. contents::
   :backlinks: none

**********
Section L2
**********

***************************************************************
Very very very very very very very loooooooooooooong section L2
***************************************************************

Section L3
==========

Very very very very very very very loooooooooooooong section L3
===============================================================

open example

No current document title ¶

By default, the contents directive prints all sections as sublist of document title. You might use :local: flag that will limit table of contents list to sections from current point in the document and bellow. If is contents with this flag used bellow the document title, it will skip it.

:orphan:

#################################
Contents without a document title
#################################

Testing ``contents::`` directive with ``:local:`` flag.

.. contents::
   :local:

**********
Section L2
**********

***************************************************************
Very very very very very very very loooooooooooooong section L2
***************************************************************

Section L3
==========

Very very very very very very very loooooooooooooong section L3
===============================================================

open example

Previous: code-block | Next: danger

On this page

contents