{"id":6000,"library":"mkdocs-jupyter","title":"MkDocs-Jupyter Plugin","description":"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.","status":"active","version":"0.26.2","language":"en","source_language":"en","source_url":"https://github.com/danielfrg/mkdocs-jupyter","tags":["MkDocs","Jupyter","documentation","notebooks","static-site-generator","plugin"],"install":[{"cmd":"pip install mkdocs-jupyter","lang":"bash","label":"Install plugin"},{"cmd":"pip install jupyter nbconvert ipykernel","lang":"bash","label":"Install Jupyter core (recommended for execution)"}],"dependencies":[{"reason":"Core dependency for the plugin to function.","package":"mkdocs","optional":false},{"reason":"Required for converting Jupyter notebooks to HTML during the build process.","package":"nbconvert","optional":false},{"reason":"Required for processing .nb.py files and for some notebook functionalities.","package":"jupytext","optional":false},{"reason":"Required for executing notebooks during the build process if 'execute: true' is enabled.","package":"ipykernel","optional":true},{"reason":"General Jupyter ecosystem tools, often needed alongside nbconvert and ipykernel for robust notebook handling.","package":"jupyter","optional":true}],"imports":[],"quickstart":{"code":"site_name: My Docs\n\nnav:\n  - Home: index.md\n  - My Notebook: notebooks/example.ipynb\n  - My Python Script: notebooks/script.py\n\nplugins:\n  - search\n  - mkdocs-jupyter:\n      execute: true  # Optional: Execute notebooks during build\n      include_source: true # Optional: Add download link for source notebooks\n      kernel_name: python3 # Optional: Specify kernel to use for execution\n","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `jupyter nbconvert ipykernel`. Check `jupyter kernelspec list` for available kernels. For large notebooks, consider splitting them or disabling execution (`execute: false`).","message":"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.","severity":"gotcha","affected_versions":"All versions with `execute: true`"},{"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`.","message":"Version incompatibilities between `mkdocs-jupyter`, `MkDocs`, `nbconvert`, and themes like `mkdocs-material` can cause plugin conflicts or rendering issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To ensure outputs are always current, explicitly set `execute: true` in your `mkdocs.yml` plugin configuration. Example: `plugins: - mkdocs-jupyter: execute: true`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure unique filenames for your notebooks and markdown files to avoid conflicts.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `mkdocs-jupyter` to version 0.23.0 or newer to ensure compatibility with `nbconvert` 7+.","message":"Older versions (prior to 0.23.0) might have issues with `nbconvert` version 7.","severity":"deprecated","affected_versions":"< 0.23.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}