Metadata-Version: 2.4
Name: jupyter-book-duplicate-toc-entry
Version: 0.1.1
Summary: Allow repeated document files in Jupyter Book TOC files.
Author: NB-TUDelft, K.Zabłocki (Zamkorus)
License-Expression: MIT
Project-URL: Homepage, https://github.com/NB-TUDelft/jupyter-book-duplicate-toc-entry
Project-URL: Repository, https://github.com/NB-TUDelft/jupyter-book-duplicate-toc-entry
Project-URL: Issues, https://github.com/NB-TUDelft/jupyter-book-duplicate-toc-entry/issues
Project-URL: Changelog, https://github.com/NB-TUDelft/jupyter-book-duplicate-toc-entry/releases
Keywords: jupyter-book,sphinx,toc,toctree,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6
Requires-Dist: sphinx-external-toc>=1.1
Dynamic: license-file

# 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:

```yaml
- 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:

```bash
uv add jupyter-book-duplicate-toc-entry
```

```bash
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:

```bash
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:

```bash
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`:

```yaml
sphinx:
  extra_extensions:
    - jupyter_book_duplicate_toc.sphinx
```

Then run `jupyter-book build` as usual.

## Releasing

Maintainers: see [RELEASING.md](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](LICENSE).
