Markdown Exec
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
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, pyodide, sh, tree, etc.
]
}
}
)
...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
...or in Zensical configuration file, as a legacy plugin:
[project.plugins.markdown-exec]
TIP: We recommend enabling Markdown Exec with the MkDocs plugin if you are using MkDocs/Zensical: it will take care of adding relevant assets (CSS/JS) to the final site when needed.
WARNING: Limitation of configuration through Markdown/PyMDown for MkDocs.
Configuration through pymdownx.superfences directly is not well supported within MkDocs for fences that require assets inclusion, like pyodide.
For these you will have to include the assets manually. In the future we will provide ways to include them automatically. In Zensical these assets are provided natively.
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!
Sponsors
And 4 more private sponsor(s).
1 maintainer
Metadata
1 maintainer
Release files for markdown-exec 1.12.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| markdown_exec-1.12.4.tar.gz | 80.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| markdown_exec-1.12.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 135.6 kB
Release files / markdown_exec-1.12.4.tar.gz
| Download URL | markdown_exec-1.12.4.tar.gz |
|---|---|
| Size | 80.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9eb8d535f69bbc85dc70b62dd9d04e65f29144de57448a87e25788c61667fbd8
|
|
BLAKE2b-256 checksum How to use checksums |
8a114484c13c38c293cb485fb730790ace11f898dd98ff758c27647369574ecd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / markdown_exec-1.12.4-py3-none-any.whl
| Download URL | markdown_exec-1.12.4-py3-none-any.whl |
|---|---|
| Size | 54.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a688e1e91bc84d8b08a26e6b8380b6ca0d83a7235f81c1609de9d832ee1b49c8
|
|
BLAKE2b-256 checksum How to use checksums |
2197912d221d873cfd6b03a76957503897b31a3e40ce6df7dcf4ed2efdd332cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
