Sphinx Jupyter Book LaTeX

1.0.0 · active · verified Thu Apr 16

Sphinx Jupyter Book LaTeX is a Sphinx extension designed to enhance LaTeX build capabilities for Jupyter Book projects. It provides a set of transforms and post-transforms that configure Sphinx to correctly handle Jupyter Book's `_toc.yml` structure and produce PDF output that closely mirrors the HTML version. Version 1.0.0 is current, and releases generally align with updates in the broader Jupyter Book ecosystem.

Common errors

```
LaTeX Error: File `some_image.png` not found. Or similar image conversion failures during PDF build.
```
cause The `sphinx.ext.imgconverter` extension, used by `sphinx-jupyterbook-latex` for image conversion, relies on the external `ImageMagick` tool which is not installed or not found in the system's PATH.

fix Install ImageMagick on your system. For Debian/Ubuntu, use `sudo apt-get install imagemagick`. For other OS, refer to ImageMagick's official installation guide.
```
LaTeX Error: Bad math environment delimiter. (Often seen with math in section titles)
```
cause Sphinx's default handling of math environments (using parentheses) can conflict when included in LaTeX's table of contents. This was a common issue in older Sphinx versions.

fix Add the following to your `latex_elements['preamble']` in `conf.py`: `r'\usepackage{etoolbox}\robustify\( \robustify\)'`.
```
PDF output contains many blank pages or incorrect page numbering/layout.
```
cause Sphinx's default LaTeX `manual` document class often forces new chapters/sections onto right-hand pages. Other issues can arise from page styling.

fix In `conf.py`, modify `latex_elements` to include `'classoptions': ',openany'` to allow chapters to start on any page. To ensure page numbers, add `\pagestyle{plain}` to your `latex_elements['preamble']`.
```
ERROR: 'sphinx-jupyterbook-latex' requires 'sphinx<5,>=3' but you have 'sphinx 5.0.1' which is incompatible.
```
cause An older version of `sphinx-jupyterbook-latex` (e.g., 0.4.6) was installed, which had an explicit upper version constraint on Sphinx, making it incompatible with Sphinx 5.x.x.

fix Upgrade `sphinx-jupyterbook-latex` to its latest version (1.0.0 or higher) which includes compatibility for Sphinx 5+: `pip install --upgrade sphinx-jupyterbook-latex`.

Warnings

gotcha For proper image conversion (e.g., PNG/GIF to PDF-compatible formats), `sphinx-jupyterbook-latex` utilizes `sphinx.ext.imgconverter`, which in turn requires the system-level tool `ImageMagick` to be installed. Without it, image rendering in PDF output may fail.
Fix: Install `ImageMagick` on your operating system. For Debian-based systems, use `sudo apt-get install imagemagick`.
breaking Older versions of `sphinx-jupyterbook-latex` (e.g., `0.4.6`) had an upper bound requirement of `sphinx<5`, causing incompatibility issues with Sphinx 5.x.x.
Fix: Upgrade `sphinx-jupyterbook-latex` to version `1.0.0` or newer to ensure compatibility with Sphinx 5 and higher: `pip install --upgrade sphinx-jupyterbook-latex`.
gotcha Embedding headings (e.g., `## My Heading`) inside admonitions or other content blocks in MyST Markdown can lead to unpredictable breakage of the document structure in Sphinx/Jupyter Book PDF output.
Fix: Avoid nesting headings within content blocks. Use bold text or a custom directive if you need to highlight text within such blocks instead of a full heading.
gotcha The `--individualpages` LaTeX builder option in Jupyter Book does not fully leverage the improvements introduced by `sphinx-jupyterbook-latex` and uses the default Sphinx LaTeX writer. This may result in inconsistent output compared to the main 'book' PDF.
Fix: Be aware of potential formatting differences. If `individualpages` output is critical, consider building the full book PDF and then splitting it, or manually adjusting LaTeX templates (advanced). The ExecutableBooks project is actively working on improving this.

Install

pip install sphinx-jupyterbook-latex Install latest version

Imports

sphinx_jupyterbook_latex
```
extensions = ['sphinx_jupyterbook_latex'] # in conf.py
```
This library is a Sphinx extension and is enabled by adding its name to the 'extensions' list in Sphinx's conf.py. Direct Python imports are rarely needed by end-users.

Quickstart

To get started, install the package via pip. Then, enable the Sphinx extension by adding 'sphinx_jupyterbook_latex' to your `extensions` list in `conf.py`. Note that ImageMagick is a required system dependency for image processing. If building with Jupyter Book, it often handles much of this configuration automatically.

# 1. Install the library
pip install sphinx-jupyterbook-latex

# 2. Add it to your Sphinx conf.py
# If you're using Jupyter Book, this extension is often enabled by default.
# For a standalone Sphinx project, add:
extensions = [
    'sphinx_jupyterbook_latex',
    # other extensions like 'myst_parser', 'jupyter_book_theme', etc.
]

# 3. Ensure ImageMagick is installed on your system for image conversion
# Example for Debian/Ubuntu:
# sudo apt-get install imagemagick

# 4. Build your book to PDF (example using jupyter-book CLI)
# jupyter-book build --builder latex your_book_folder
# For Sphinx, use: make latexpdf

view raw JSON →