Skip to content

Examples

Real-world examples demonstrating the power and flexibility of markdown-code-runner.

Here are a few examples demonstrating the usage of markdown-code-runner:

⭐ Example 1: Simple code block

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 -->

⭐ Example 2: Multiple code blocks

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 -->

After running `markdown-code-runner`:
```markdown
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 -->

⭐ Example 2: Multiple code blocks

<!​-- CODE:SKIP --> 

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 -->

<!​-- CODE:SKIP --> 

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 -->

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 -->

Usage Ideas

.*?", "", content, flags=re.DOTALL) -->

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:

💻 Idea 2: Show command-line output

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:

bash markdown-code-runner export PATH=~/micromamba/bin:$PATH echo 'bash' markdown-code-runner --help echo '```' 

Which is rendered as:
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```bash
usage: markdown-code-runner [-h] [-o OUTPUT] [-d] [-v]
                            [--no-backtick-standardize]
                            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   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
  --no-backtick-standardize
                        Disable backtick standardization (default: enabled for
                        separate output files, disabled for in-place)

📊 Idea 3: Generating Markdown Tables

Use the pandas library to create a Markdown table from a DataFrame. The following example demonstrates how to create a table with random data:

```python markdown-code-runner 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:

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
|   Column A |   Column B |   Column C |
|-----------:|-----------:|-----------:|
|         52 |         93 |         15 |
|         72 |         61 |         21 |
|         83 |         87 |         75 |
|         75 |         88 |        100 |
|         24 |          3 |         22 |

<!-- OUTPUT:END -->

### :art: Idea 4: Generating Visualizations

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:

<!-- CODE:SKIP --> <!-- This is here otherwise the next example gets executed -->
```python markdown-code-runner
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)

ℹ NOTE: This output is disabled here because GitHub Markdown doesn't support inline image HTML. This will work on other Markdown renderers.

📄 Idea 5: Generating a table from CSV data

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:

```python markdown-code-runner 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:

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
| Name    |   Age |   Score |
|:--------|------:|--------:|
| Alice   |    30 |      90 |
| Bob     |    25 |      85 |
| Charlie |    22 |      95 |

<!-- OUTPUT:END -->

### :star: Idea 5: Displaying API data as a list

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:SKIP --> <!-- This prevents the example below from getting executed -->
```markdown
<!-- 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:

  • delectus aut autem (User ID: 1, Completed: False)
  • quis ut nam facilis et officia qui (User ID: 1, Completed: False)
  • fugiat veniam minus (User ID: 1, Completed: False)
  • et porro tempora (User ID: 1, Completed: True)
  • laboriosam mollitia et enim quasi adipisci quia provident illum (User ID: 1, Completed: False)

🦀 Idea 6: Run a Rust program

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.

```rust markdown-code-runner filename=main.rs fn main() { println!("Hello, world!"); } 

Which when executed produces:

<!-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- rustc main.rs && ./main -->
<!-- echo '```' -->
<!-- CODE:END -->

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

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!

<!-- OUTPUT:END -->
Which is rendered as:

<!​-- CODE:START -->

<!​-- CODE:END --> <!​-- OUTPUT:START -->

  • delectus aut autem (User ID: 1, Completed: False)
  • quis ut nam facilis et officia qui (User ID: 1, Completed: False)
  • fugiat veniam minus (User ID: 1, Completed: False)
  • et porro tempora (User ID: 1, Completed: True)
  • laboriosam mollitia et enim quasi adipisci quia provident illum (User ID: 1, Completed: False)

<!​-- OUTPUT:END -->

🦀 Idea 6: Run a Rust program

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.

```rust markdown-code-runner filename=main.rs fn main() { println!("Hello, world!"); } 

Which when executed produces:

<!​-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- rustc main.rs && ./main -->
<!-- echo '```' -->
<!​-- CODE:END -->

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

<!​-- OUTPUT:END -->

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!

<!-- OUTPUT:END -->

## More Ideas

Here are additional creative uses for `markdown-code-runner`:

### Auto-Generate Package Statistics

```python markdown-code-runner
# Fetch package download statistics
import requests

url = "https://api.pepy.tech/api/v2/projects/markdown-code-runner"
# Note: This would require an API key in practice
print("Download statistics would appear here!")

Document Your API

```python markdown-code-runner

Auto-generate API documentation from docstrings

import inspect from markdown_code_runner import update_markdown_file

Get function signature

sig = inspect.signature(update_markdown_file) print(f"Signature: update_markdown_file{sig}") print()

Get docstring

doc = update_markdown_file.doc if doc: print(doc) 

### Include Test Results

```python markdown-code-runner
# Show test coverage or test results
import subprocess
result = subprocess.run(
    ["python", "-c", "print('All tests passed!')"],
    capture_output=True,
    text=True
)
print(result.stdout)

Dynamic Configuration Examples

```python markdown-code-runner

Generate configuration examples from actual defaults

print("Default markers used by markdown-code-runner:") print() print("| Marker | Purpose |") print("|--------|---------|") print("| <!-- CODE:START --> | Start of hidden Python code |") print("| <!-- CODE:END --> | End of hidden code block |") print("| <!-- CODE:BASH:START --> | Start of hidden Bash code |") print("| <!-- OUTPUT:START --> | Start of output section |") print("| <!-- OUTPUT:END --> | End of output section |") print("| <!-- CODE:SKIP --> | Skip the next code block |") ```