mkdocs-jupyter

mkdocs-jupyter is a MkDocs plugin that lets you add Jupyter notebooks (.ipynb) and Python scripts (.py, via jupytext) directly into your documentation site’s navigation. It renders them as pages that keep the familiar Jupyter notebook look, so data-science and research projects can publish executable, richly formatted content alongside regular Markdown docs.

It supports rendering notebooks in the same style as Jupyter, Jupyter themes, optional execution of notebooks at build time, ipywidgets, MkDocs table-of-contents integration, and an option to include the notebook source. By registering as a MkDocs plugin, it slots into any existing MkDocs (including Material) site with a few lines of configuration.

What You Get

• A MkDocs plugin that adds .ipynb and .py files to your docs navigation
• Jupyter-style rendering of notebook cells, outputs, and themes
• Optional execution of notebooks at build time before conversion
• Support for ipywidgets and MkDocs table-of-contents integration
• An option to include downloadable notebook source alongside the rendered page

Common Use Cases

• Publishing data-science tutorials and analyses as documentation pages
• Turning example notebooks into a library’s official docs site
• Building executable documentation that re-runs notebooks on each build
• Mixing Jupyter notebooks with Markdown pages in a MkDocs Material site

Under The Hood

Architecture - The package lives under src/mkdocs_jupyter/. plugin.py implements the MkDocs plugin interface, hooking into the build to detect notebook/script files and route them through convert.py, which drives conversion via nbconvert2.py (a customized nbconvert pipeline) and preprocessors.py. config.py handles plugin options (execution, themes, source inclusion) and utils.py holds shared helpers. The result is HTML injected into MkDocs pages with Jupyter-style CSS.

Tech Stack - Pure Python packaged with a src/ layout, depending on mkdocs, nbconvert, jupytext, and pygments/nbformat from the Jupyter stack. It ships bundled notebook and theme CSS assets and integrates with Jupyter’s HTML exporter for cell rendering.

Code Quality - The project has a focused test suite (8 test files) plus Codecov coverage and CI badges in the README. The module split between plugin wiring, conversion, and configuration is clean, though development activity has slowed, reflected in the lower repo-health cadence score.

API Design - There is no code-level API to learn: usage is declarative, adding mkdocs-jupyter under plugins: in mkdocs.yml and setting a handful of options such as execute, theme, and include_source. This makes onboarding very easy for anyone already using MkDocs, and the demo site documents each option.