Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pawamoy/markdown-exec
Utilities to execute code blocks in Markdown files.
https://github.com/pawamoy/markdown-exec
literate-programming markdown python-markdown
Last synced: 10 days ago
JSON representation
Utilities to execute code blocks in Markdown files.
- Host: GitHub
- URL: https://github.com/pawamoy/markdown-exec
- Owner: pawamoy
- License: isc
- Created: 2022-02-11T22:48:50.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-08T21:58:03.000Z (4 months ago)
- Last Synced: 2024-10-23T08:53:32.043Z (17 days ago)
- Topics: literate-programming, markdown, python-markdown
- Language: Python
- Homepage: https://pawamoy.github.io/markdown-exec
- Size: 2.19 MB
- Stars: 105
- Watchers: 2
- Forks: 8
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-starred - pawamoy/markdown-exec - Utilities to execute code blocks in Markdown files. (markdown)
README
# 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://gitpod.io/#https://github.com/pawamoy/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
With `pip`:
```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!