markdown-code-runner
Advanced tools
Automatically execute code blocks within a Markdown file 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.
The package is hosted on GitHub: https://github.com/basnijholt/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.
Install markdown-code-runner via pip:
pip install markdown-code-runner
To get started with markdown-code-runner, follow these steps:
Add code blocks to your Markdown file using either of the following methods:
Method 1 (show your code): Use a triple backtick code block with the language specifier python markdown-code-runner.
Example:
```python markdown-code-runner
print('Hello, world!')
```
(Optionally, you can place some text between the code block and the output markers)
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->
or for Bash:
```bash markdown-code-runner
echo 'Hello, world!'
```
(Optionally, you can place some text between the code block and the output markers)
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->
Method 2 (hide your code): Place the code between <!-- CODE:START --> and <!-- CODE:END --> markers. Add the output markers <!-- OUTPUT:START --> and <!-- OUTPUT:END --> where you want the output to be displayed.
Example:
This is an example code block:
<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->
or for Bash:
This is an example code block:
<!-- CODE:BASH:START -->
<!-- MY_VAR="Hello, World!" -->
<!-- echo $MY_VAR -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->
Run markdown-code-runner on your Markdown file:
markdown-code-runner /path/to/your/markdown_file.md
The output of the code block will be automatically executed and inserted between the output markers.
To use markdown-code-runner, simply import the update_markdown_file function from the package and call it with the path to your Markdown file:
from markdown_code_runner import update_markdown_file
update_markdown_file("path/to/your/markdown_file.md")
Here are a few examples demonstrating the usage of markdown-code-runner:
This is an example of a simple hidden code block:
<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->
After running markdown-code-runner:
This is an example of a simple code block:
<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Hello, world!
<!-- OUTPUT:END -->
Here are two code blocks:
First code block:
<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the first code block.
<!-- OUTPUT:END -->
Second code block:
<!-- CODE:START -->
<!-- print('Hello again!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the second code block.
<!-- OUTPUT:END -->
After running markdown-code-runner:
Here are two code blocks:
First code block:
<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Hello, world!
<!-- OUTPUT:END -->
Second code block:
<!-- CODE:START -->
<!-- print('Hello again!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Hello again!
<!-- OUTPUT:END -->
Markdown Code Runner can be used for various purposes, such as creating Markdown tables, generating visualizations, and showcasing code examples with live outputs. Here are some usage ideas to get you started:
You can use markdown-code-runner to automatically update your Markdown files in a CI environment.
The following example demonstrates how to configure a GitHub Actions workflow that updates your README.md whenever changes are pushed to the main branch.
Create a new workflow file in your repository at .github/workflows/markdown-code-runner.yml.
Add the following content to the workflow file:
name: Update README.md
on:
push:
branches:
- main
pull_request:
jobs:
update_readme:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v3
with:
persist-credentials: false
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v3
with:
python-version: '3.x'
- name: Install markdown-code-runner
run: |
python -m pip install --upgrade pip
pip install markdown-code-runner
# Install dependencies you're using in your README.md
- name: Install other Python dependencies
run: |
pip install pandas tabulate pytest matplotlib requests
# Rust is only needed for an example in our README.md
- name: Set up Rust
uses: actions-rs/toolchain@v1
with:
toolchain: stable
profile: minimal
- name: Run update-readme.py
run: markdown-code-runner --verbose README.md
- name: Commit updated README.md
id: commit
run: |
git add README.md
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
if git diff --quiet && git diff --staged --quiet; then
echo "No changes in README.md, skipping commit."
echo "commit_status=skipped" >> $GITHUB_ENV
else
git commit -m "Update README.md"
echo "commit_status=committed" >> $GITHUB_ENV
fi
- name: Push changes
if: env.commit_status == 'committed'
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: ${{ github.head_ref }}
main branch, updating your README.md with the latest outputs from your code blocks.For more information on configuring GitHub Actions, check out the official documentation.
Use markdown-code-runner to display the output of a command-line program. For example, the following Markdown file shows the helper options of this package.
Using a backtick bash code block:
export PATH=~/micromamba/bin:$PATH
echo '```bash'
markdown-code-runner --help
echo '```'
Which is rendered as:
usage: markdown-code-runner [-h] [-o OUTPUT] [-d] [-v] input
Automatically update Markdown files with code block output.
positional arguments:
input Path to the input Markdown file.
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Path to the output Markdown file. (default: overwrite
input file)
-d, --verbose Enable debugging mode (default: False)
-v, --version show program's version number and exit
Use the pandas library to create a Markdown table from a DataFrame. The following example demonstrates how to create a table with random data:
import pandas as pd
import numpy as np
# Generate random data
np.random.seed(42)
data = np.random.randint(1, 101, size=(5, 3))
# Create a DataFrame and column names
df = pd.DataFrame(data, columns=["Column A", "Column B", "Column C"])
# Convert the DataFrame to a Markdown table
print(df.to_markdown(index=False))
Which is rendered as:
| Column A | Column B | Column C |
|---|---|---|
| 52 | 93 | 15 |
| 72 | 61 | 21 |
| 83 | 87 | 75 |
| 75 | 88 | 100 |
| 24 | 3 | 22 |
Create a visualization using the matplotlib library and save it as an image. Then, reference the image in your Markdown file. The following example demonstrates how to create a bar chart.
Using a triple-backtick code block:
import matplotlib.pyplot as plt
import io
import base64
from urllib.parse import quote
# Example data for the plot
x = [1, 2, 3, 4, 5]
y = [2, 4, 6, 8, 10]
# Create a simple line plot
plt.plot(x, y)
plt.xlabel("X-axis")
plt.ylabel("Y-axis")
plt.title("Sample Line Plot")
# Save the plot to a BytesIO buffer
buf = io.BytesIO()
plt.savefig(buf, format='png')
plt.close()
# Encode the buffer as a base64 string
data = base64.b64encode(buf.getvalue()).decode('utf-8')
# Create an inline HTML img tag with the base64 string
from urllib.parse import quote
img_html = f'<img src="data:image/png;base64,{quote(data)}" alt="Sample Line Plot"/>'
print(img_html)
:information_source: NOTE: This output is disabled here because GitHub Markdown doesn't support inline image HTML. This will work on other Markdown renderers.
Suppose you have a CSV file containing data that you want to display as a table in your Markdown file.
You can use pandas to read the CSV file, convert it to a DataFrame, and then output it as a Markdown table.
Using a triple-backtick code block:
import pandas as pd
csv_data = "Name,Age,Score\nAlice,30,90\nBob,25,85\nCharlie,22,95"
with open("sample_data.csv", "w") as f:
f.write(csv_data)
df = pd.read_csv("sample_data.csv")
print(df.to_markdown(index=False))
Which is rendered as:
| Name | Age | Score |
|---|---|---|
| Alice | 30 | 90 |
| Bob | 25 | 85 |
| Charlie | 22 | 95 |
You can use markdown-code-runner to make API calls and display the data as a list in your Markdown file.
In this example, we'll use the requests library to fetch data from an API and display the results as a list.
Using a hidden code block:
<!-- CODE:START -->
<!-- import requests -->
<!-- response = requests.get("https://jsonplaceholder.typicode.com/todos?_limit=5") -->
<!-- todos = response.json() -->
<!-- for todo in todos: -->
<!-- print(f"- {todo['title']} (User ID: {todo['userId']}, Completed: {todo['completed']})") -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- OUTPUT:END -->
Which is rendered as:
We can use markdown-code-runner to write Rust code to a file and then a hidden bash code block to run the code and display the output.
The code below is actually executed, check out the README.md in plain text to see how this works.
fn main() {
println!("Hello, world!");
}
Which when executed produces:
Hello, world!
These are just a few examples of how you can use Markdown Code Runner to enhance your Markdown documents with dynamic content. The possibilities are endless!
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.
Contributions are welcome! To contribute, please follow these steps:
Please report any issues or bugs on the GitHub issue tracker: https://github.com/basnijholt/markdown-code-runner/issues
Thank you for your interest in markdown-code-runner!
FAQs
Automatically execute code blocks within a Markdown file and update the output in-place
We found that markdown-code-runner demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.