Jupyter Book Duplicate ToC

This package allows a Jupyter Book _toc.yml file to list the same document file more than once.

It installs a small sitecustomize hook so the normal jupyter-book command uses the patched parser during its early TOC validation. It also provides jupyter_book_duplicate_toc.sphinx for the later Sphinx parse.

The patch keeps the first parsed document entry. Later TOC entries point to that same document as leaf links, so repeated chapter or root pages do not expand their original child tree.

Use standard Jupyter Book file-entry syntax when naming a repeated page:

- file: intro.md
  title: Welcome!

The caption key belongs on TOC groups, not on file entries. This package raises an error if a repeated file entry uses caption, with a suggestion to use title.

Install

From PyPI:

uv add jupyter-book-duplicate-toc-entry

pip install jupyter-book-duplicate-toc-entry

From the NB_TUDelft channel on anaconda.org. Add conda-forge as well, since that is where the dependencies come from:

conda install -c NB_TUDelft -c conda-forge jupyter-book-duplicate-toc-entry

To follow the unreleased main branch instead of a release, install from Git:

uv add "jupyter-book-duplicate-toc-entry @ git+https://github.com/NB-TUDelft/jupyter-book-duplicate-toc-entry.git"

Configure

Add the Sphinx extension to your Jupyter Book _config.yml:

sphinx:
  extra_extensions:
    - jupyter_book_duplicate_toc.sphinx

Then run jupyter-book build as usual.

Releasing

Maintainers: see RELEASING.md. In short, bump the version in pyproject.toml, __init__.py and uv.lock, commit, then push a vX.Y.Z tag — GitHub Actions publishes to PyPI and anaconda.org from the tag.

License

MIT — see LICENSE.