markdown-exec

What it is and what it does

Markdown Exec is a Markdown extension that transforms code blocks into executable snippets. When you mark a code block with `exec="on"`, the extension runs that code and injects the output back into the document in place of the original block. It works as a plugin for MkDocs or as a standalone Markdown extension, integrating with pymdown-extensions' SuperFences to handle multiple languages including Python, bash, and console sessions.

The package is designed for documentation workflows where you want code examples to stay synchronized with their actual output—write a Python snippet that generates HTML or a bash command that lists files, and the rendered documentation automatically shows what that code produces. It supports optional ANSI color rendering for terminal output via the `ansi` extra, and can be configured to expect specific exit codes or handle errors gracefully.

Use it for:

• Auto-generate API documentation by executing code examples that produce formatted output
• Keep shell command examples in docs synchronized with their real output
• Build documentation sites where Python snippets compute and display results
• Create reproducible tutorials where code blocks run during the build and embed their results
• Generate tables or formatted lists in Markdown by executing Python code that produces them

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Executes code blocks embedded in Markdown files and replaces them with their output, supporting Python, bash, and other languages with optional ANSI color rendering.

Yes, if you maintain documentation with code examples that need to stay current. The low install friction, active maintenance, permissive license, and lack of known vulnerabilities make it safe to adopt. Install with caution only if your documentation build process runs untrusted code, since execution happens at build time—otherwise it's a straightforward win for keeping examples accurate.

Install

markdown-exec on PyPI

pip install markdown-exec

uv add markdown-exec

poetry add markdown-exec

Installing markdown-exec

Before you install

Low friction: pure Python wheel with a single runtime dependency (pymdown-extensions). Actively maintained with recent releases; last commit 2026-07-08. Requires Python 3.10 or later.

License in practice

ISC license is permissive and imposes minimal restrictions; suitable for both open-source and commercial use without copyleft obligations.

Quickstart

pip install markdown-exec

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,
            }]
        }
    }
)

Requires Python 3.10 or later; pymdown-extensions must be installed as a runtime dependency.

Verify before relying

• Security implications of executing arbitrary code blocks during documentation builds
• Performance impact when processing large numbers of code blocks or long-running scripts
• Whether pyodide support is fully functional or still experimental

Package facts

Evidence: markdown_exec-1.12.3-py3-none-any.whl

Keywords: markdown, python, exec, shell, bash, mkdocs

Tags

More Software Development packages