MkDocs-Jupyter Plugin

0.26.2 · active · verified Tue Apr 14

mkdocs-jupyter is an MkDocs plugin that enables the seamless integration of Jupyter notebooks (.ipynb files) and Jupytext-generated Python scripts (.nb.py files) directly into your MkDocs documentation. It allows for rendering notebooks, optionally executing them during the build process, supports theme integration, and offers granular control over the visibility of notebook cells and outputs using tags. The current stable version is 0.26.2, with active development and regular updates.

Warnings

gotcha MkDocs Material specific Markdown features (like admonitions, info blocks) do not render correctly within Jupyter notebook markdown cells. This is due to `nbconvert` not supporting these extensions, leading to plain text rendering.
Fix: For complex Markdown features, consider using standard MkDocs `.md` files or simplifying notebook markdown. CSS tweaks might partially help for styling, but not for functionality.
gotcha Enabling notebook execution (`execute: true`) can lead to build failures if required Jupyter dependencies (like `jupyter`, `nbconvert`, `ipykernel`) are not installed, if the specified `kernel_name` is unavailable, or if notebooks are excessively large, causing timeouts.
Fix: Install `jupyter nbconvert ipykernel`. Check `jupyter kernelspec list` for available kernels. For large notebooks, consider splitting them or disabling execution (`execute: false`).
gotcha Version incompatibilities between `mkdocs-jupyter`, `MkDocs`, `nbconvert`, and themes like `mkdocs-material` can cause plugin conflicts or rendering issues.
Fix: Pin specific versions of `mkdocs`, `mkdocs-jupyter`, and `mkdocs-material` in your `requirements.txt` to ensure consistent builds and avoid unexpected breaks after updates. For example: `mkdocs==1.5.3`, `mkdocs-material==9.5.3`, `mkdocs-jupyter==0.26.2`.
gotcha By default, notebooks are not executed during the `mkdocs build` process. Their outputs will only reflect the state of the `.ipynb` file when it was last saved.
Fix: To ensure outputs are always current, explicitly set `execute: true` in your `mkdocs.yml` plugin configuration. Example: `plugins: - mkdocs-jupyter: execute: true`.
gotcha Having both a `.ipynb` file (e.g., `example.ipynb`) and a `.md` file (e.g., `example.md`) with the same base name in your `docs` directory can lead to unexpected rendering behavior or errors.
Fix: Ensure unique filenames for your notebooks and markdown files to avoid conflicts.
deprecated Older versions (prior to 0.23.0) might have issues with `nbconvert` version 7.
Fix: Upgrade `mkdocs-jupyter` to version 0.23.0 or newer to ensure compatibility with `nbconvert` 7+.

Install

pip install mkdocs-jupyter Install plugin
pip install jupyter nbconvert ipykernel Install Jupyter core (recommended for execution)

Quickstart

To use mkdocs-jupyter, you primarily configure it in your `mkdocs.yml` file under the `plugins` section. After installation, create a `docs` directory with your markdown (`.md`), Jupyter notebooks (`.ipynb`), or Jupytext Python scripts (`.py`). Reference these files in your `nav` configuration. Ensure you have a basic `index.md` for your homepage.

site_name: My Docs

nav:
  - Home: index.md
  - My Notebook: notebooks/example.ipynb
  - My Python Script: notebooks/script.py

plugins:
  - search
  - mkdocs-jupyter:
      execute: true  # Optional: Execute notebooks during build
      include_source: true # Optional: Add download link for source notebooks
      kernel_name: python3 # Optional: Specify kernel to use for execution

view raw JSON →