Skip to content

Jupyter Notebooks

MkDocs Material provides excellent support for Jupyter notebooks through the mkdocs-jupyter plugin, allowing you to seamlessly integrate interactive notebooks into your documentation.

Overview

The mkdocs-jupyter plugin enables you to:

  • Render Jupyter notebooks (.ipynb files) directly in your documentation
  • Support Jupytext files (.nb.py files) for better version control
  • Execute notebooks during the build process to ensure outputs are current
  • Customize appearance with theme integration
  • Control visibility of inputs, outputs, and specific cells using tags

Configuration

The plugin is configured in your mkdocs.yml file:

plugins:
  - mkdocs-jupyter:
      execute: true              # Execute notebooks during build
      include_source: true       # Add download link for source notebooks
      theme: dark               # Use dark theme for code cells
      include: ["*.ipynb", "*.nb.py"]  # File patterns to include
      execute_ignore: ["notebooks/drafts/*.ipynb"]  # Skip certain files
      allow_errors: false        # Fail build on notebook errors
      kernel_name: python3       # Specify kernel to use
      ignore_h1_titles: false    # Include H1 from notebooks
      show_input: true          # Show input cells by default
      no_input: false           # Don't hide all inputs
      remove_tag_config:
        remove_cell_tags:
          - "hide"              # Hide cells with these tags
          - "hide-cell"
        remove_all_outputs_tags:
          - "hide-output"       # Hide outputs for tagged cells
        remove_input_tags:
          - "hide-input"        # Hide input for tagged cells

Features

Direct Notebook Integration

Simply add .ipynb files to your docs directory and reference them in your navigation:

nav:
  - Notebooks:
    - Introduction: notebooks/intro.ipynb
    - Data Analysis: notebooks/analysis.ipynb

Jupytext Support

Use .nb.py files for better version control and IDE support:

# %% [markdown]
# # My Notebook
# This is a markdown cell in a Python script!

# %%
print("This is a code cell")

Cell Visibility Control

Control what parts of your notebooks are visible using cell tags:

  • hide - Hide the entire cell
  • hide-input - Show only the output
  • hide-output - Show only the input

Execution Control

  • Execute on build: Ensures outputs are always current
  • Selective execution: Skip drafts or specific notebooks
  • Error handling: Choose to allow or fail on errors

Theme Integration

The plugin integrates seamlessly with Material theme:

  • Consistent styling with your documentation
  • Dark/light theme support
  • Syntax highlighting
  • Copy buttons on code cells

Best Practices

1. Organize Notebooks

Keep notebooks in a dedicated directory:

docs/
├── notebooks/
│   ├── tutorials/
│   ├── examples/
│   └── drafts/

2. Use Meaningful Names

Name notebooks descriptively: - ✅ data-visualization-tutorial.ipynb - ❌ notebook1.ipynb

3. Add Markdown Cells

Include explanatory text in markdown cells to guide readers through your notebooks.

4. Clean Outputs

For version control, consider clearing outputs before committing:

jupyter nbconvert --clear-output --inplace notebook.ipynb

5. Use Cell Tags

Tag cells appropriately for documentation:

{
  "tags": ["hide-input"]
}

Examples

Basic Notebook

See our test notebook for a simple example.

Jupytext Example

Check out the Python script notebook demonstrating Jupytext format.

Advanced Features

Interactive Widgets

Notebooks can include interactive widgets when using appropriate kernels and extensions.

Multiple Kernels

The plugin supports multiple kernels (Python, R, Julia, etc.). Specify the kernel in your notebook metadata or plugin configuration.

Troubleshooting

Common Issues

  1. Notebook not rendering: Ensure the file extension is included in the include pattern
  2. Execution failures: Check kernel availability and dependencies
  3. Missing outputs: Verify execute: true is set in configuration

Debug Mode

Enable verbose output to debug issues:

mkdocs build --verbose

Advanced Configuration

Custom CSS for Notebooks

Add custom styling for notebook elements:

/* docs/assets/stylesheets/notebooks.css */
.jupyter-wrapper .jp-Cell {
    border-radius: 4px;
    margin: 0.5em 0;
}

Performance Optimization

For large notebooks:

  1. Use execute_ignore for notebooks that don't need fresh outputs
  2. Consider splitting very long notebooks
  3. Use caching strategies for expensive computations

Integration with Other Features

Jupyter notebooks work well with other MkDocs Material features:

  • Search: Notebook content is searchable
  • Navigation: Notebooks appear in the navigation tree
  • Tags: Use the tags plugin to categorize notebooks
  • Social cards: Generate preview cards for notebook pages

Resources