Repolode
Submit
danielfrg

danielfrg/mkdocs-jupyter

A MkDocs plugin that converts Jupyter Notebook and Jupytext .py files into documentation pages, with optional execution and theme styling.

View on GitHubWebsite
Stars
509
Forks
65
Open issues
0
Last commit
3 days ago

What is it?

mkdocs-jupyter lets you add Jupyter Notebooks directly to a MkDocs site's navigation, so tutorials and analysis write-ups can live alongside regular Markdown pages. It accepts .ipynb files as well as Python scripts in Jupytext format, and renders them in the same style as standard Jupyter Notebook output, with support for Jupyter themes and ipywidgets.

The plugin can optionally execute notebooks before conversion, ignore execution for selected files, and hide code input or prompts globally or per cell via tags. Notebook titles and table-of-contents entries are derived from headers, and YAML frontmatter can set standard MkDocs page metadata. Math rendering uses MathJax, and conversion results are cached between builds.

It is intended for documentation sites where code examples need to be runnable and their outputs visible, without maintaining separate exported HTML files.

Key features

  • 01Adds .ipynb and Jupytext .py files directly to the MkDocs navigation.
  • 02Optionally executes notebooks before conversion, with per-file exclusions.
  • 03Hides code input or prompts globally or for tagged cells.
  • 04Supports Jupyter themes, ipywidgets, and MathJax math rendering.
  • 05Includes a download link for notebook source and caches conversion results.

Use cases

  • Publishing data science tutorials with runnable code and visible outputs in a docs site.
  • Building API or library documentation that includes executable examples.
  • Writing technical blog posts or course material in notebook format on MkDocs.

Quick start

  1. 1

    Install the plugin from PyPI

    pip install mkdocs-jupyter
  2. 2

    Add the plugin to plugins in mkdocs.yml and list your notebooks or .py files in nav

Things to know

  • Only works as a plugin for MkDocs, so you need an existing MkDocs site.

In collections

Static site generators & documentation tools

Topics

#jupyter#mkdocs#documentation#python#notebook#static-site#blogging#jupyter-notebook

FAQ

What is mkdocs-jupyter?
A MkDocs plugin that converts Jupyter Notebook and Jupytext .py files into documentation pages, with optional execution and theme styling. mkdocs-jupyter lets you add Jupyter Notebooks directly to a MkDocs site's navigation, so tutorials and analysis write-ups can live alongside regular Markdown pages. It accepts .ipynb files as well as Python scripts in Jupytext format, and renders them in the same style as standard Jupyter Notebook output, with support for Jupyter themes and ipywidgets.
Is mkdocs-jupyter free to use? What license does it have?
mkdocs-jupyter is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is mkdocs-jupyter still maintained?
Actively maintained. The last commit to mkdocs-jupyter was on Nov 5, 2026.
What can I use mkdocs-jupyter for?
Publishing data science tutorials with runnable code and visible outputs in a docs site. Building API or library documentation that includes executable examples. Writing technical blog posts or course material in notebook format on MkDocs.
How do I install mkdocs-jupyter?
Install the plugin from PyPI: pip install mkdocs-jupyter Add the plugin to plugins in mkdocs.yml and list your notebooks or .py files in nav
Where can I get mkdocs-jupyter?
The source code and installation instructions are on GitHub: https://github.com/danielfrg/mkdocs-jupyter

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects