Documentation with Jupyter Book

Jupyter Book builds a website from Markdown (MyST) files and Jupyter notebooks.

This template uses Jupyter Book 2. The configuration is docs/myst.yml.

Write¶

• Pages are Markdown files and notebooks in docs/; the landing page is docs/index.md.

• Add a page by creating the file and listing it under toc: in myst.yml. Pages not listed there are not built.

• Images go in docs/images/.

• Notebooks (.ipynb) can be listed like any page. They are shown with the outputs saved in them, not re-executed: Figure 5 kinematics is an example.

Preview locally¶

uv sync --extra docs           # or: pip install -e ".[docs]"
cd docs && jupyter book start  # serves the book at http://localhost:3000 and reloads on save

Jupyter Book needs Node.js 18 or later. If it is not installed, the first run offers to install a private copy.

Publish¶

.github/workflows/docs.yml builds the book on every pull request, so a broken page fails the check. On every push to main, it also publishes the book to GitHub Pages, at https://<organisation>.github.io/<repository>/.

Before the first publication, enable Pages once: in the repository’s Settings → Pages, set Source to GitHub Actions. See GitHub’s Pages documentation and Jupyter Book’s deployment guide.

Like the other workflows, it only runs on public repositories.

Learn more¶

• Jupyter Book documentation: installing, building and publishing a book.

• MyST guide: the Markdown flavour used by every page. Most useful sections:

  • MyST Markdown quickstart

  • Typography, directives and admonitions

  • Cross-references

  • Table of contents, which is the toc: in myst.yml

  • Notebooks

  • Page frontmatter: title, authors, DOI and license shown at the top of a page

  • Website themes: the options used in myst.yml under site: