markdown-exec 0.3.0

Utilities to execute code blocks in Markdown files.

Markdown Exec

Utilities to execute code blocks in Markdown files.

For example, you write a Python code block that computes some HTML, and this HTML is injected in place of the code block.

Requirements

Markdown Exec requires Python 3.7 or above.

To install Python 3.7, I recommend using pyenv.

# install pyenv
git clone https://github.com/pyenv/pyenv ~/.pyenv

# setup pyenv (you should also put these three lines in .bashrc or similar)
export PATH="${HOME}/.pyenv/bin:${PATH}"
export PYENV_ROOT="${HOME}/.pyenv"
eval "$(pyenv init -)"

# install Python 3.7
pyenv install 3.7.12

# make it available globally
pyenv global system 3.7.12

Installation

With pip:

pip install markdown-exec

Configuration

This extension relies on the SuperFences extension of PyMdown Extensions.

To allow execution of code blocks, configure a custom fence from Python:

from markdown import Markdown
from markdown_exec import formatter, validator

Markdown(
    extensions=["pymdownx.superfences"],
    extension_configs={
        "pymdownx.superfences": {
            "custom_fences": [
                {
                    "name": "python",
                    "class": "python",
                    "validator": validator,
                    "format": formatter,
                }
            ]
        }
    }
)

...or in MkDocs configuration file, as a Markdown extension:

# mkdocs.yml
markdown_extensions:
- pymdownx.superfences:
    custom_fences:
    - name: python
      class: python
      validator: !!python/name:markdown_exec.validator
      format: !!python/name:markdown_exec.formatter

...or in MkDocs configuration file, as a plugin:

# mkdocs.yml
plugins:
- search
- markdown-exec

Usage

You are now able to execute code blocks instead of displaying them:

```python exec="on"
print("Hello Markdown!")
```

The exec option will be true for every possible value except 0, no, off and false (case insensitive).

To capture the output of your code, Markdown Exec patches the print function so that it writes to a buffer instead of standard output.

See usage for more details, and the gallery for more examples!