{"id":4981,"library":"markdown-exec","title":"markdown-exec","description":"markdown-exec is a Python library that provides utilities to execute code blocks directly within Markdown files. It's commonly used with MkDocs and PyMdown-Extensions to inject dynamic content, such as script outputs or interactive elements, into documentation. The library sees active development with releases typically occurring every few months.","status":"active","version":"1.12.1","language":"en","source_language":"en","source_url":"https://github.com/pawamoy/markdown-exec","tags":["markdown","code execution","documentation","mkdocs","pydoc","superfences"],"install":[{"cmd":"pip install markdown-exec","lang":"bash","label":"Base installation"},{"cmd":"pip install \"markdown-exec[ansi]\"","lang":"bash","label":"With ANSI color support"}],"dependencies":[{"reason":"Required for configuring custom code fences, specifically `pymdownx.superfences`.","package":"Pymdown-Extensions"},{"reason":"Optional, provides ANSI color rendering support when installing with the `[ansi]` extra.","package":"pygments-ansi-color","optional":true},{"reason":"Highly recommended for integrating markdown-exec as a plugin or extension in documentation sites.","package":"MkDocs","optional":true}],"imports":[{"note":"These symbols are typically used when programmatically configuring custom fences for `pymdownx.superfences`.","symbol":"formatter, validator","correct":"from markdown_exec import formatter, validator"}],"quickstart":{"code":"import os\n\n# mkdocs.yml configuration example\n# plugins:\n#   - search\n#   - markdown-exec\n# markdown_extensions:\n#   - pymdownx.superfences\n\n# Example Markdown content (e.g., in docs/index.md)\nmarkdown_content = '''\n# My Executable Documentation\n\nThis is a simple example of markdown-exec in action.\n\n```python exec=\"on\"\nimport sys\nprint(f\"Hello from Python {sys.version.split(' ')}!\")\n```\n'''\n\n# To simulate execution without a full MkDocs setup, one would typically process this\n# via the Markdown library with the markdown-exec extension enabled.\n# However, the primary intended use is within MkDocs.\n# For a true quickstart, an MkDocs project is implicitly assumed.\n# This example is illustrative of the Markdown content.\n\n# To make it runnable for an agent, assume an MkDocs build process:\n# 1. Create a dummy mkdocs.yml (if not present)\n# 2. Create a dummy docs/index.md with the content above\n# 3. Run `mkdocs build` or `mkdocs serve`\n\n# This Python snippet shows how the markdown content looks, not how to run it directly in Python for output capture.\n# The actual execution happens via the Markdown extension or MkDocs plugin.","lang":"python","description":"To quickly get started, create an `mkdocs.yml` file and a Markdown file (e.g., `docs/index.md`). Enable the `markdown-exec` plugin and `pymdownx.superfences` extension in your `mkdocs.yml`. Then, add a code block with `exec=\"on\"` in your Markdown file. The example illustrates the structure for MkDocs integration, which is the recommended approach."},"warnings":[{"fix":"Upgrade Python to 3.9 or higher.","message":"Support for Python 3.8 was dropped in version 1.10.0. Users on Python 3.8 or older must upgrade their Python environment or remain on an older version of markdown-exec.","severity":"breaking","affected_versions":">=1.10.0"},{"fix":"Enable markdown-exec as an MkDocs plugin (recommended) or manually include required assets if configuring `pymdownx.superfences` custom fences directly.","message":"When using the `pyodide` fence or other fences requiring asset inclusion, configuring `pymdownx.superfences` directly (without the MkDocs plugin) may require manual inclusion of assets (CSS/JS) for proper rendering. The MkDocs plugin handles this automatically.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `pymdownx.superfences` is listed in your `markdown_extensions` in `mkdocs.yml` or passed to `markdown.Markdown` when used programmatically.","message":"If `pymdownx.superfences` is not enabled in your Markdown extensions configuration, `markdown-exec` will error out early. This is a common oversight when setting up the library.","severity":"gotcha","affected_versions":">=1.11.0"},{"fix":"Upgrade to markdown-exec 1.10.3 or newer to ensure proper output escaping.","message":"Output escaping for strings printed directly was improved in versions 1.10.2 and 1.10.3 to address display issues and potential vulnerabilities. Older versions might render unescaped output.","severity":"gotcha","affected_versions":"<1.10.3"},{"fix":"Avoid using code annotations immediately after code blocks that employ `source='tabbed-left'` (or `tabbed-right`) or consider alternative rendering options.","message":"When using `markdown-exec` with `Material for MkDocs` and `source='tabbed-left'` (or `tabbed-right`), code annotations placed immediately after the code block may break due to the generated tab structure. The annotation logic in Material for MkDocs expects the list to be directly after the code block.","severity":"gotcha","affected_versions":"All versions with Material for MkDocs and tabbed source"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}