MkDocs Jupyter Plugin

Render Jupyter notebooks as documentation pages.

Core Attributes

pip install mkdocs-jupyter

What It Does

This plugin converts Jupyter notebook (.ipynb) files into documentation pages. It renders saved notebook outputs - it does NOT run a live Jupyter server.

Configuration

plugins:
  - mkdocs-jupyter:
      include_source: true
      execute: false
      allow_errors: false
      ignore_h1_titles: false
      include_requirejs: true

Usage

Basic Usage

Place notebooks in your docs directory:

docs/
├── index.md
├── tutorials/
│   ├── introduction.ipynb
│   └── advanced.ipynb
└── examples/
    └── data-analysis.ipynb

Notebooks appear in navigation automatically!

Creating Good Notebook Docs

Structure:

1. Markdown cell: Title and introduction
2. Code cell: Imports
3. Markdown cell: Explanation
4. Code cell: Example code
5. Output cell: Results
6. Markdown cell: Summary

Example Notebook

Cell 1 (Markdown):

# Data Analysis Tutorial

This notebook demonstrates basic data analysis with pandas.

Cell 2 (Code):

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

Cell 3 (Markdown):

## Loading Data

We'll load a sample dataset:

Cell 4 (Code):

df = pd.DataFrame({
    'A': np.random.randn(100),
    'B': np.random.randn(100)
})
df.head()

Configuration Options

Features

Rendered Content

The plugin preserves: - Code cells with syntax highlighting - Output cells (text, tables, plots) - Markdown cells - LaTeX equations - HTML output - Interactive widgets (with RequireJS)

Supported Output Types

Text:

print("Hello, World!")
# Output: Hello, World!

DataFrames:

df.describe()
# Rendered as formatted table

Plots:

plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
# Rendered as image

HTML:

from IPython.display import HTML
HTML('<h1>Custom HTML</h1>')

Best Practices

1. Clear All Unnecessary Outputs

Before committing:

Cell > All Output > Clear

Then re-run only the cells you want to show.

2. Use Markdown Liberally

Add context between code cells:

## Data Preprocessing

Before analysis, we clean the data:

3. Keep Notebooks Focused

One topic per notebook: - data-loading.ipynb - data-cleaning.ipynb - visualization.ipynb

4. Add Metadata

Use notebook metadata for configuration:

{
  "mkdocs": {
    "execute": false,
    "allow_errors": false
  }
}

5. Test Notebook Flow

Restart kernel and run all cells before committing:

Kernel > Restart & Run All

6. Optimize Cell Outputs

• Limit DataFrame display rows
• Use reasonable plot sizes
• Clear debug outputs
• Save large results to files

# Good
df.head(10)

# Bad - too much output
df  # Shows entire DataFrame

7. Add Requirements

Document required packages:

# Required packages:
# pip install pandas numpy matplotlib seaborn

Execute Mode

When to use execute mode: - Notebooks are fast (<1 second) - Outputs change frequently - Automated testing of notebooks - CI/CD validation

When NOT to use: - Long-running computations - Notebooks with external dependencies - Random or time-dependent outputs - Production documentation

Interactive Widgets

For interactive Jupyter widgets:

from ipywidgets import interact

@interact(x=(0, 10))
def square(x):
    return x ** 2

Requires:

include_requirejs: true

Troubleshooting

Notebook Not Rendering

Check: 1. File extension is .ipynb 2. Notebook is in docs directory 3. JSON is valid (not corrupted)

Missing Outputs

Solutions: 1. Re-run cells in Jupyter 2. Save notebook with outputs 3. Check include_source setting

Widget Not Working

Solutions: 1. Enable include_requirejs 2. Use compatible widget versions 3. Check browser console

Tips

1. Save notebooks with outputs before committing
2. Use clear, descriptive cell outputs
3. Add explanatory markdown cells
4. Keep execution time short
5. Document dependencies
6. Test in fresh environment