sphinx_external_toc

What it is and what it does

sphinx-external-toc is a Sphinx extension that moves table-of-contents definition from a bottom-up, file-by-file approach (using toctree directives scattered throughout documentation) to a top-down, centralized YAML file. Instead of adding toctree directives within each page, you define the entire site structure in a single _toc.yml file, specifying which documents appear where, in what order, and with what options. This is particularly useful for large documentation projects where the structure needs to be managed as a whole rather than piecemeal.

The extension supports recursive nesting, glob patterns for matching multiple files, external URLs, custom titles, and advanced toctree options like numbering styles (numerical, roman, alphabetic), depth limits, and caption text. It is included by default in Jupyter Book, making it a natural choice for projects in that ecosystem. The extension also allows auto-exclusion of documents not mentioned in the ToC, helping keep documentation organized and intentional.

Use it for:

• Define a multi-chapter book or tutorial structure in a single YAML file instead of editing toctree directives across many source files.
• Manage large Jupyter Book projects where the documentation hierarchy needs to be centralized and version-controlled as one artifact.
• Apply consistent numbering schemes (roman numerals, alphabetic, etc.) across multiple sections without repeating configuration in each file.
• Automatically exclude undocumented or orphaned files from the build by setting external_toc_exclude_missing.
• Reorganize documentation structure without touching individual source files—only edit the YAML.
• Use glob patterns to include entire directories of files matching a naming convention without listing each one explicitly.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that defines documentation site-maps in a single YAML file using a top-down approach, instead of scattered toctree directives throughout source files.

Yes, if you use Sphinx and want a cleaner, more maintainable way to manage documentation structure. The extension is actively maintained, has no known vulnerabilities, low install friction, and is already the default in Jupyter Book. It is most valuable for projects with many pages or frequent structural changes. For small, simple documentation, the benefit is marginal.

Install

sphinx-external-toc on PyPI

pip install sphinx-external-toc

uv add sphinx-external-toc

poetry add sphinx-external-toc

Installing sphinx_external_toc

Before you install

Low friction installation with a pure Python wheel. Actively maintained as of 2026-01-16 with recent commits. Four runtime dependencies (click, pyyaml, sphinx, sphinx-multitoc-numbering) are all standard Sphinx ecosystem packages.

License in practice

Permissive license treatment means you can use this in commercial and proprietary projects without restriction or obligation to share modifications.

Quickstart

pip install sphinx-external-toc

# In conf.py:
extensions = ["sphinx_external_toc"]
external_toc_path = "_toc.yml"

# In _toc.yml:
root: intro
entries:
  - file: chapter1
  - file: chapter2

Requires Sphinx and Python 3.9 or later. The external_toc_path is always read as a Unix path relative to the source directory.

Verify before relying

• Whether the extension handles complex nested structures (depth limits, performance with large ToCs) without documented constraints.
• Compatibility with Sphinx versions beyond those implied by the current dependency specification.
• Real-world adoption rate or production use beyond Jupyter Book's default inclusion.

Package facts

Evidence: sphinx_external_toc-1.1.0-py3-none-any.whl

Keywords: sphinx, extension, toc

Tags

More Python Modules packages