Mkdocs-Ipymd

Mkdocs plugin for Interactive Python

This plugin allows you to use python, in VSCode interactive fashion, to create docs. The motivation was having a way to create interactive examples in the documentation, without increasing the git repository size.

Installation

pip install mkdocs-ipymd

or with poetry:

poetry add mkdocs-ipymd

Usage

1. Add the plugin to your mkdocs.yml:

plugins:
  - ipymd

2. Create a python file ".py" or ".ipy" in the docs folder:

And use the following syntax to include the file in your markdown:

# %%
import numpy as np
import matplotlib.pyplot as plt

# %%
msg = "Hello World"
print(msg)

# %%
msg = "Hello not again"
print(msg)

# %% [markdown]

## This is a markdown cell

### With some content

And some math

$$
E = mc^2
$$

The # %% is a cell separator, and the content of the cell is executed as python code.

3. Add the file to your mkdocs.yml nav (optional)

nav:
  - Home: index.md
  - Examples:
    - file1.md
    - file2.md

Important: you must add the file with ".md" extension, even if the file is a python file.