Installation and usage

Installation

sphinx-structured-toc is available on PyPI. Install it with pip:

pip install sphinx-structured-toc

or with uv:

uv add sphinx-structured-toc

The extension requires Python 3.10 or later, Sphinx 7.x, and docutils 0.21.2 or later.

Add sphinx_structured_toc to the extensions list in conf.py:

extensions = ["sphinx_structured_toc"]

No other configuration is required. The extension ships a small CSS file that is automatically copied into your build’s _static directory and linked from every page.

A minimal example

A domain contains one or more slice blocks. Each slice contains one or more :doc: item lines, one per line:

The model layer
~~~~~~~~~~~~~~~

..  domain::

    ..  slice:: Models

        :doc:`Field types <demo-targets/field-types-reference>`
        :doc:`Custom fields <demo-targets/custom-fields-how-to>`

    ..  slice:: Queries

        :doc:`Lookup expressions <demo-targets/lookup-expressions-how-to>`
        :doc:`Queryset operations <demo-targets/queryset-operations-how-to>`

This renders as a single <nav> representing the domain. It contains one list of two slices.

Each slice begins with its name, followed by a list of links with CSS separators:

The struture of each domain is a nested list:

ul: the domain
    li: the slice
        ul:
            li: link
            li: link

Disambiguating repeated link text

Screen reader users can’t tell multiple links apart if they have the same name. Even a single link might have an uninformative name, whose meaning is immediately clear to visual users from its context but not to someone using a screen reader.

The slice and domain trailing keywords add the slice name and/or the domain name to a link’s accessible name. The additional context is always added in the order item, slice, domain:

..  domain::

    ..  slice:: Models

        :doc:`Reference <models/reference>` slice

    ..  slice:: Queries

        :doc:`Reference <queries/reference>` slice

Here the two Reference links get accessible names Reference, Models and Reference, Queries. The visible text remains Reference in both cases.

domain can be used as well as or instead of slice when slice alone is not sufficient to provide the required context:

..  domain:: French verbs

    ..  slice:: Conjugation

        :doc:`Reference <french/conjugation/reference>` domain

..  domain:: German verbs

    ..  slice:: Conjugation

        :doc:`Reference <german/conjugation/reference>` domain

The accessible names become Reference, French verbs and Reference, German verbs.

Ambiguity warnings

The extension emits a warning for link names that collide. This can be suppressed per particular domain with :suppress-warnings: flag:

..  domain::
    :suppress-warnings: