Sphinx External ToC

1.1.0 · active · verified Thu Apr 16

Sphinx External ToC is a Sphinx extension that enables a top-down approach to defining the documentation's site-map (Table of Contents) using a single YAML file, typically `_toc.yml`. This contrasts with Sphinx's default bottom-up `toctree` directives spread across multiple reStructuredText files. The library is currently at version 1.1.0 and maintains an active release cadence, providing new features and bug fixes.

Common errors

```
WARNING: document isn't included in any toctree
```
cause A documentation file exists in the source directory but is not referenced in the `_toc.yml` file, and `external_toc_exclude_missing` is not set to `True`.

fix Either include the document in your `_toc.yml`, add `:orphan:` metadata at the top of the document, or set `external_toc_exclude_missing = True` in your `conf.py`.
```
YAMLError: while parsing a block mapping
```
cause The `_toc.yml` file contains syntax errors, such as incorrect indentation, missing colons, or invalid YAML structure.

fix Carefully review your `_toc.yml` file for proper YAML syntax. Use a YAML linter or validator to identify and correct structural issues. Pay close attention to indentation and key-value pair formatting.
```
The root document 'your_root_doc' was not found.
```
cause The file specified as `root` in your `_toc.yml` does not exist or its path is incorrect relative to your Sphinx source directory.

fix Verify that the file specified under `root:` in `_toc.yml` exists and that its path is correct. Remember that paths in `_toc.yml` are relative to the source directory and do not include file extensions.

Warnings

breaking Version 0.3.0 dropped support for Python 3.6. Projects using older Python versions must upgrade their environment to Python 3.7+ (or 3.9+ for current versions).
Fix: Upgrade your Python environment to 3.9 or newer. Ensure `requires_python='>=3.9'` is met.
breaking As of v1.0.0, `sphinx-external-toc` explicitly requires `sphinx-multitoc-numbering`. Older installations that do not have this dependency might fail after upgrade.
Fix: Ensure `sphinx-multitoc-numbering` is installed alongside `sphinx-external-toc` (e.g., `pip install sphinx-external-toc sphinx-multitoc-numbering`).
gotcha Changes to the `_toc.yml` file, especially the `root` entry, may not always be reflected in the Sphinx build output unless the build cache is cleared.
Fix: After modifying `_toc.yml`, clear your Sphinx build cache by deleting the `_build` directory (or using `make clean` if a Makefile is present) before rebuilding your documentation.
gotcha By default, Sphinx emits a 'WARNING: document isn't included in any toctree' for files not explicitly listed in your `_toc.yml`. While `sphinx-external-toc` manages the main ToC, explicitly unlisted files will still trigger this warning.
Fix: To suppress this warning for documents intentionally excluded from the ToC, set `external_toc_exclude_missing = True` in your `conf.py`, or add `:orphan:` metadata to the top of each unlisted document file.
gotcha Version compatibility between `sphinx-external-toc` and Sphinx itself can be a source of issues. For example, v0.3.1 explicitly added support for Sphinx 5. Newer Sphinx versions might introduce incompatibilities with older `sphinx-external-toc` releases.
Fix: Always check the `sphinx-external-toc` documentation and release notes for tested Sphinx versions. When encountering unexpected behavior, try updating `sphinx-external-toc` to its latest version, or pin its version to one known to be compatible with your Sphinx installation.

Install

pip install sphinx-external-toc Install latest version

Imports

sphinx_external_toc
```
extensions = [
    'sphinx_external_toc',
    # Other extensions...
]
```
The extension is enabled by adding its module name to the 'extensions' list in conf.py.

Quickstart

To quickly set up `sphinx-external-toc`, first add `sphinx_external_toc` to your `extensions` list in `conf.py`. Then, create a `_toc.yml` file in your source directory to define your documentation structure. This YAML file replaces the need for `.. toctree::` directives within your ReStructuredText or Markdown files. The `external_toc_path`, `use_multitoc_numbering`, and `external_toc_exclude_missing` options provide granular control over the ToC generation.

# conf.py (in your Sphinx project's source directory)
import os

project = 'My Docs'
copyright = '2026, My Name'
extensions = [
    'sphinx_external_toc',
    'myst_parser' # Example: if using Markdown
]

# Optional: Configure the external ToC
external_toc_path = '_toc.yml' # Default: '_toc.yml'
use_multitoc_numbering = True # Default: True, enables numbered sections
external_toc_exclude_missing = True # Default: False, prevents warnings for files not in ToC

# --- Example _toc.yml (in your Sphinx project's source directory) ---
# root: index
# chapters:
#   - file: intro
#   - file: part1
#     sections:
#       - file: part1/chapter1
#       - file: part1/chapter2
#   - file: tutorial
#   - url: https://example.com
#     title: External Link

view raw JSON →