Metadata-Version: 2.1
Name: markdown-exec
Version: 0.1.0
Summary: Utilities to execute code blocks in Markdown files.
License: UNKNOWN
Author-email: Timothée Mazzucotelli <pawamoy@pm.me>
Requires-Python: >=3.7
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
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
Requires-Dist: pymdown-extensions>=9
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.

## Requirements

Markdown Exec requires Python 3.7 or above.

<details>
<summary>To install Python 3.7, I recommend using <a href="https://github.com/pyenv/pyenv"><code>pyenv</code></a>.</summary>

```bash
# 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
```
</details>

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

```yaml
markdown_extensions:
- pymdownx.superfences:
    custom_fences:
    - name: python
      class: python
      validator: !!python/name:markdown_exec.validator
      format: !!python/name:markdown_exec.formatter
```

## Usage

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

````md
```python exec="on"
print("Some Python code")
```
````

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

The standard output and error of executed Python code blocks is not captured
and will be written to the terminal, as usual.

If you want to "inject" contents into the page, you can use these two functions
in your code blocks (they are available in the global context of execution):

- `output_html(text)`: inject the HTML text passed as argument. 
- `output_markdown(text)`: convert the text passed as argument to HTML and then inject it.

WARNING: You can call these functions only once, as they internally raise an exception.

HTML Example:

=== "Markdown"

    ````md
    System information:

    ```python exec="yes"
    import platform
    output_html(
        f"""
        <code>
        machine: {platform.machine()}
        version: {platform.version()}
        platform: {platform.platform()}
        system: {platform.system()}
        </code>
        """
    )
    ```
    ````

=== "Rendered"

    System information:

    ```
    machine: x86_64
    version: #1 SMP PREEMPT Tue, 01 Feb 2022 21:42:50 +0000
    platform: Linux-5.16.5-arch1-1-x86_64-with-glibc2.33
    system: Linux
    ```

Markdown Example:

=== "Markdown"

    ````md
    System information:

    ```python exec="yes"
    import platform
    output_markdown(
        f"""
        - machine: `{platform.machine()}`
        - version: `{platform.version()}`
        - platform: `{platform.platform()}`
        - system: `{platform.system()}`
        """
    )
    ```
    ````

=== "Rendered"

    System information:

    - machine: `x86_64`
    - version: `#1 SMP PREEMPT Tue, 01 Feb 2022 21:42:50 +0000`
    - platform: `Linux-5.16.5-arch1-1-x86_64-with-glibc2.33`
    - system: `Linux`
