Markdown Code Runner

Automatically execute code blocks within Markdown files and update the output in-place

markdown-code-runner is a Python package that automatically executes code blocks within a Markdown file, including hidden code blocks, and updates the output in-place. This package is particularly useful for maintaining Markdown files with embedded code snippets, ensuring that the output displayed is up-to-date and accurate. It also enables the generation of content such as tables, plots, and other visualizations directly from the code.

Features

• Automatically execute code blocks, including hidden code blocks, within a Markdown file
• Allows hidden code blocks (i.e., code blocks that are not displayed in the Markdown file) to generate content like tables, plots, etc.
• Works with Python and Bash code blocks
• Keeps the output of the code blocks up-to-date
• :octocat: Easily integrates with GitHub Actions
• No external dependencies and works with Python 3.7+
• Execute all languages by using the file code blocks and executing it with bash (see Rust example)

Why Use Markdown Code Runner?

When creating Markdown files with code examples, it's essential to keep the output of these code snippets accurate and up-to-date. Manually updating the output can be time-consuming and error-prone, especially when working with large files or multiple collaborators. In addition, there might be cases where hidden code blocks are needed to generate content such as tables, plots, and other visualizations without displaying the code itself in the Markdown file.

markdown-code-runner solves this problem by automatically executing the code blocks, including hidden ones, within a Markdown file and updating the output in-place. This ensures that the displayed output is always in sync with the code, and content generated by hidden code blocks is seamlessly integrated.

Quick Example

Here's how simple it is to use markdown-code-runner:

Hidden Code Block:

<!​-- CODE:START -->
<!​-- print('Hello, world!') -->
<!​-- CODE:END -->
<!​-- OUTPUT:START -->
This will be replaced by the output.
<!​-- OUTPUT:END -->

Visible Code Block:

```python markdown-code-runner
print('Hello, world!')
```
<!​-- OUTPUT:START -->
This will be replaced by the output.
<!​-- OUTPUT:END -->

After running markdown-code-runner:

<!​-- OUTPUT:START -->
<!​-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Hello, world!

<!​-- OUTPUT:END -->

Get Started → View Examples →

License

markdown-code-runner is released under the MIT License. Please include the LICENSE file when using this package in your project, and cite the original source.