Metadata-Version: 2.1
Name: markdown-exec
Version: 0.7.4
Summary: Utilities to execute code blocks in Markdown files.
License: ISC
Author-email: Timothée Mazzucotelli <pawamoy@pm.me>
Requires-Python: >=3.7
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Project-URL: Changelog, https://pawamoy.github.io/markdown-exec/changelog
Project-URL: Discussions, https://github.com/pawamoy/markdown-exec/discussions
Project-URL: Documentation, https://pawamoy.github.io/markdown-exec
Project-URL: Funding, https://github.com/sponsors/pawamoy
Project-URL: Gitter, https://gitter.im/markdown-exec/community
Project-URL: Homepage, https://pawamoy.github.io/markdown-exec
Project-URL: Issues, https://github.com/pawamoy/markdown-exec/issues
Project-URL: Repository, https://github.com/pawamoy/markdown-exec
Description-Content-Type: text/markdown

# Markdown Exec

[![ci](https://github.com/pawamoy/markdown-exec/workflows/ci/badge.svg)](https://github.com/pawamoy/markdown-exec/actions?query=workflow%3Aci)
[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://pawamoy.github.io/markdown-exec/)
[![pypi version](https://img.shields.io/pypi/v/markdown-exec.svg)](https://pypi.org/project/markdown-exec/)
[![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/pawamoy/markdown-exec)
[![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/markdown-exec/community)

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`:
```bash
pip install markdown-exec
```

## Configuration

This extension relies on the
[SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/)
extension of
[PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/).

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

```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:

```yaml
# 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:

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

## Usage

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

````md
```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](https://pawamoy.github.io/markdown-exec/usage/) for more details,
and the [gallery](https://pawamoy.github.io/markdown-exec/gallery/) for more examples!

