Metadata-Version: 2.1
Name: markdown-exec
Version: 0.3.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
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
Description: # 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, 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/) for more details,
        and the [gallery](https://pawamoy.github.io/markdown-exec/gallery/) for more examples!

