# Markdown Exec
[](https://github.com/pawamoy/markdown-exec/actions?query=workflow%3Aci)
[](https://pawamoy.github.io/markdown-exec/)
[](https://pypi.org/project/markdown-exec/)
[](https://app.gitter.im/#/room/#markdown-exec:gitter.im)
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
```bash
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](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,
}
# ...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:
```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
# ...one fence for each language we support:
# bash, console, md, markdown, py, python, pycon, sh, tree
```
...or in MkDocs configuration file, as a plugin:
```yaml
# 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:
````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).
Below you can see an example of running a bash script that is expected to
return a non-zero exit code:
````md
```bash exec="1" source="tabbed-left" returncode="2"
grep extra_css README.md && exit 2
```
````
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!
Raw data
{
"_id": null,
"home_page": null,
"name": "markdown-exec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "markdown, python, exec, shell, bash, mkdocs",
"author": null,
"author_email": "=?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>",
"download_url": "https://files.pythonhosted.org/packages/ad/2f/9cd26ebda86b1e63f6785e39f40b824cab190d14b926cf2205041e981771/markdown_exec-1.10.2.tar.gz",
"platform": null,
"description": "# Markdown Exec\n\n[](https://github.com/pawamoy/markdown-exec/actions?query=workflow%3Aci)\n[](https://pawamoy.github.io/markdown-exec/)\n[](https://pypi.org/project/markdown-exec/)\n[](https://app.gitter.im/#/room/#markdown-exec:gitter.im)\n\nUtilities to execute code blocks in Markdown files.\n\nFor example, you write a Python code block that computes some HTML,\nand this HTML is injected in place of the code block.\n\n## Installation\n\n```bash\npip install \"markdown-exec[ansi]\"\n```\n\nThe `ansi` extra provides the necessary bits (`pygments-ansi-color` and a CSS file)\nto render ANSI colors in HTML code blocks. The CSS file is automatically added\nto MkDocs' `extra_css` when Markdown Exec is activated via `plugins` (see below).\n\n## Configuration\n\nThis extension relies on the\n[SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/)\nextension of\n[PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/).\n\nTo allow execution of code blocks,\nconfigure a custom fence from Python:\n\n```python\nfrom markdown import Markdown\nfrom markdown_exec import formatter, validator\n\nMarkdown(\n extensions=[\"pymdownx.superfences\"],\n extension_configs={\n \"pymdownx.superfences\": {\n \"custom_fences\": [\n {\n \"name\": \"python\",\n \"class\": \"python\",\n \"validator\": validator,\n \"format\": formatter,\n }\n # ...one fence for each language we support:\n # bash, console, md, markdown, py, python, pycon, sh, tree\n ]\n }\n }\n)\n```\n\n...or in MkDocs configuration file, as a Markdown extension:\n\n```yaml\n# mkdocs.yml\nmarkdown_extensions:\n- pymdownx.superfences:\n custom_fences:\n - name: python\n class: python\n validator: !!python/name:markdown_exec.validator\n format: !!python/name:markdown_exec.formatter\n # ...one fence for each language we support:\n # bash, console, md, markdown, py, python, pycon, sh, tree\n```\n\n...or in MkDocs configuration file, as a plugin:\n\n```yaml\n# mkdocs.yml\nplugins:\n- search\n- markdown-exec\n\n# SuperFences must still be enabled!\nmarkdown_extensions:\n- pymdownx.superfences\n```\n\nWe do recommend enabling Markdown Exec with the MkDocs plugin\nif you are using MkDocs: it will take care of adding relevant\nassets (CSS/JS) to the final site when needed. \n\n## Usage\n\nYou are now able to execute code blocks instead of displaying them:\n\n````md\n```python exec=\"on\"\nprint(\"Hello Markdown!\")\n```\n````\n\nThe `exec` option will be true for every possible value except `0`, `no`, `off` and `false` (case insensitive).\n\nBelow you can see an example of running a bash script that is expected to\nreturn a non-zero exit code:\n\n````md\n```bash exec=\"1\" source=\"tabbed-left\" returncode=\"2\"\ngrep extra_css README.md && exit 2\n```\n````\n\nSee [usage](https://pawamoy.github.io/markdown-exec/usage/) for more details,\nand the [gallery](https://pawamoy.github.io/markdown-exec/gallery/) for more examples!\n",
"bugtrack_url": null,
"license": null,
"summary": "Utilities to execute code blocks in Markdown files.",
"version": "1.10.2",
"project_urls": {
"Changelog": "https://pawamoy.github.io/markdown-exec/changelog",
"Discussions": "https://github.com/pawamoy/markdown-exec/discussions",
"Documentation": "https://pawamoy.github.io/markdown-exec",
"Funding": "https://github.com/sponsors/pawamoy",
"Gitter": "https://gitter.im/markdown-exec/community",
"Homepage": "https://pawamoy.github.io/markdown-exec",
"Issues": "https://github.com/pawamoy/markdown-exec/issues",
"Repository": "https://github.com/pawamoy/markdown-exec"
},
"split_keywords": [
"markdown",
" python",
" exec",
" shell",
" bash",
" mkdocs"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1bfb70f79ef0be6a2f7ea59466fcaf3f2c5a6017ad60d2c4a0358149d1266f0c",
"md5": "c21d7badfd8b0f1e572e37b4f247f985",
"sha256": "cc92e8e9a3dbd02648732a7d25ad696b30cbaf28cd7b3de939545331ef5f3ec1"
},
"downloads": -1,
"filename": "markdown_exec-1.10.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c21d7badfd8b0f1e572e37b4f247f985",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 34397,
"upload_time": "2025-03-18T21:41:25",
"upload_time_iso_8601": "2025-03-18T21:41:25.835788Z",
"url": "https://files.pythonhosted.org/packages/1b/fb/70f79ef0be6a2f7ea59466fcaf3f2c5a6017ad60d2c4a0358149d1266f0c/markdown_exec-1.10.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad2f9cd26ebda86b1e63f6785e39f40b824cab190d14b926cf2205041e981771",
"md5": "6e6d640b167c41eefc4e2d3d0566f297",
"sha256": "1f5e199e60b6afea86e11515f096a53d06d8b32687ab6cd45f12551d3490692f"
},
"downloads": -1,
"filename": "markdown_exec-1.10.2.tar.gz",
"has_sig": false,
"md5_digest": "6e6d640b167c41eefc4e2d3d0566f297",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 80842,
"upload_time": "2025-03-18T21:41:27",
"upload_time_iso_8601": "2025-03-18T21:41:27.141384Z",
"url": "https://files.pythonhosted.org/packages/ad/2f/9cd26ebda86b1e63f6785e39f40b824cab190d14b926cf2205041e981771/markdown_exec-1.10.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-18 21:41:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pawamoy",
"github_project": "markdown-exec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "markdown-exec"
}
JSON
