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.
pip install mkdocs-jupyterNo compatibility data collected yet for this library.
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.
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.
Install `jupyter nbconvert ipykernel`. Check `jupyter kernelspec list` for available kernels. For large notebooks, consider splitting them or disabling execution (`execute: false`).
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`.
To ensure outputs are always current, explicitly set `execute: true` in your `mkdocs.yml` plugin configuration. Example: `plugins: - mkdocs-jupyter: execute: true`.
Ensure unique filenames for your notebooks and markdown files to avoid conflicts.
Upgrade `mkdocs-jupyter` to version 0.23.0 or newer to ensure compatibility with `nbconvert` 7+.
Downgrade your MkDocs installation to a version compatible with mkdocs-jupyter (e.g., `mkdocs==1.5.3`) or wait for an update to mkdocs-jupyter that resolves this compatibility. `pip install "mkdocs<1.6"`
Install the necessary Jupyter dependencies: `pip install jupyter nbconvert ipykernel`. Verify that a kernel is available and registered (`jupyter kernelspec list`). If notebooks are not executing, ensure `execute: true` is set under the `mkdocs-jupyter` plugin configuration in your `mkdocs.yml`.
Double-check that the notebook file paths in your `mkdocs.yml` navigation are correct relative to your `docs_dir`. For images, ensure they are in the correct location relative to the notebook or consider setting `use_directory_urls: false` in `mkdocs.yml` if relative image paths are causing issues.