Name | markdown-exec JSON |
Version |
1.8.1
JSON |
| download |
home_page | None |
Summary | Utilities to execute code blocks in Markdown files. |
upload_time | 2024-04-15 16:53:34 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.8 |
license | ISC |
keywords |
markdown
python
exec
shell
bash
mkdocs
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# 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://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
```
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.8",
"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/03/3a/931a9662ba30b932db482d10c244f7c7caf764c8ce56440000810d3f365e/markdown_exec-1.8.1.tar.gz",
"platform": null,
"description": "# Markdown Exec\n\n[![ci](https://github.com/pawamoy/markdown-exec/workflows/ci/badge.svg)](https://github.com/pawamoy/markdown-exec/actions?query=workflow%3Aci)\n[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://pawamoy.github.io/markdown-exec/)\n[![pypi version](https://img.shields.io/pypi/v/markdown-exec.svg)](https://pypi.org/project/markdown-exec/)\n[![gitpod](https://img.shields.io/badge/gitpod-workspace-blue.svg?style=flat)](https://gitpod.io/#https://github.com/pawamoy/markdown-exec)\n[![gitter](https://badges.gitter.im/join%20chat.svg)](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\nWith `pip`:\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\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": "ISC",
"summary": "Utilities to execute code blocks in Markdown files.",
"version": "1.8.1",
"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": "",
"digests": {
"blake2b_256": "7f8a5bad538693fd123bc5fbd62aae70258195abc85c2acd5109e158d9e95083",
"md5": "6c62a9ffb270abac3cf84f2f86435c3f",
"sha256": "63c769ebf202b1c1f97822c72e4467d39e151b741aeb94758b3de20066ed3b5f"
},
"downloads": -1,
"filename": "markdown_exec-1.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c62a9ffb270abac3cf84f2f86435c3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25768,
"upload_time": "2024-04-15T16:53:32",
"upload_time_iso_8601": "2024-04-15T16:53:32.673912Z",
"url": "https://files.pythonhosted.org/packages/7f/8a/5bad538693fd123bc5fbd62aae70258195abc85c2acd5109e158d9e95083/markdown_exec-1.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "033a931a9662ba30b932db482d10c244f7c7caf764c8ce56440000810d3f365e",
"md5": "ba038d8948985da8e0ce645e10a32f25",
"sha256": "1fe4e344f3dc000dd7e764ab1ee21d14e4e15c91afc8c6d35f18d694693eb696"
},
"downloads": -1,
"filename": "markdown_exec-1.8.1.tar.gz",
"has_sig": false,
"md5_digest": "ba038d8948985da8e0ce645e10a32f25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23205,
"upload_time": "2024-04-15T16:53:34",
"upload_time_iso_8601": "2024-04-15T16:53:34.908013Z",
"url": "https://files.pythonhosted.org/packages/03/3a/931a9662ba30b932db482d10c244f7c7caf764c8ce56440000810d3f365e/markdown_exec-1.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 16:53:34",
"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"
}