Skip to main content

Utilities to execute code blocks in Markdown files.

Project description

Markdown Exec

ci documentation pypi version gitpod gitter

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.

Installation

With pip:

pip install markdown-exec[ansi]

The ansi extra provides the necessary bits (pygments-ansi-color and a CSS file) to render ANSI colors in HTML code blocks. The CSS file is automatically added to MkDocs' extra_css when Markdown Exec is activated via plugins (see below).

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,
                }
                # ...one fence for each language we support:
                # bash, console, md, markdown, py, python, pycon, sh, tree
            ]
        }
    }
)

...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
    # ...one fence for each language we support:
    # bash, console, md, markdown, py, python, pycon, sh, tree

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

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

# SuperFences must still be enabled!
markdown_extensions:
- pymdownx.superfences

We do recommend enabling Markdown Exec with the MkDocs plugin if you are using MkDocs: it will take care of adding relevant assets (CSS/JS) to the final site when needed.

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).

Below you can see an example of running a bash script that is expected to return a non-zero exit code:

```bash exec="1" source="tabbed-left" returncode="2"
grep extra_css README.md && exit 2
```

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markdown_exec-1.9.3.tar.gz (74.7 kB view hashes)

Uploaded Source

Built Distribution

markdown_exec-1.9.3-py3-none-any.whl (27.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page