Skip to content

Clean up README: remove emojis and add SVG logo #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
basnijholt merged 5 commits into from
Jan 14, 2026
Merged

Clean up README: remove emojis and add SVG logo #40

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d80ba37
Clean up README: remove emojis and add SVG logo
basnijholt Jan 14, 2026
a41d303
Right-align the logo in README
basnijholt Jan 14, 2026
5dd1b0c
Move logo below header to avoid underline crossing
basnijholt Jan 14, 2026
333e32c
Remove redundant GitHub link from README
basnijholt Jan 14, 2026
8960379
Fix Rust example anchor link (#idea-6 → #idea-7)
basnijholt Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 46 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,28 @@
# :rocket: Markdown Code Runner
# Markdown Code Runner

![](https://media.githubusercontent.com/media/basnijholt/nijho.lt/main/content/project/markdown-code-runner/featured.jpg)
<img src="https://raw.githubusercontent.com/basnijholt/markdown-code-runner/main/docs/assets/logo.svg" alt="Markdown Code Runner Logo" align="right" style="width: 200px;" />

<!-- SECTION:intro:START -->
`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.
<!-- SECTION:intro:END -->

The package is hosted on GitHub: [https://github.com/basnijholt/markdown-code-runner](https://github.com/basnijholt/markdown-code-runner)

:book: **Documentation**: [https://markdown-code-runner.nijho.lt](https://markdown-code-runner.nijho.lt)
**Documentation**: [https://markdown-code-runner.nijho.lt](https://markdown-code-runner.nijho.lt)

<!-- SECTION:features:START -->
## :star: Features
- :rocket: Automatically execute code blocks, including hidden code blocks, within a Markdown file
- :eyes: Allows hidden code blocks (i.e., code blocks that are not displayed in the Markdown file) to generate content like tables, plots, etc.
- :snake: :shell: Works with Python and Bash code blocks
- :white_check_mark: Keeps the output of the code blocks up-to-date
- :octocat: Easily integrates with GitHub Actions
- :tada: No external dependencies and works with Python 3.7+
- :globe_with_meridians: Execute *all* languages by using the file code blocks and executing it with bash (see [Rust :crab: example](#crab-idea-6-run-a-rust-program))
## 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
- 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](#idea-7-run-a-rust-program))
<!-- SECTION:features:END -->

<!-- SECTION:problem-statement:START -->
## :question: Problem Statement
## Problem Statement

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.
Expand All @@ -34,32 +32,32 @@ In addition, there might be cases where hidden code blocks are needed to generat
This ensures that the displayed output is always in sync with the code, and content generated by hidden code blocks is seamlessly integrated.
<!-- SECTION:problem-statement:END -->

## :books: Table of Contents
## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [:computer: Installation](#computer-installation)
- [:rocket: Quick Start](#rocket-quick-start)
- [:snake: Python API](#snake-python-api)
- [:book: Examples](#book-examples)
- [:star: Example 1: Simple code block](#star-example-1-simple-code-block)
- [:star: Example 2: Multiple code blocks](#star-example-2-multiple-code-blocks)
- [:bulb: Usage Ideas](#bulb-usage-ideas)
- [:gear: Idea 1: Continuous Integration with GitHub Actions](#gear-idea-1-continuous-integration-with-github-actions)
- [:computer: Idea 2: Show command-line output](#computer-idea-2-show-command-line-output)
- [:bar_chart: Idea 3: Generating Markdown Tables](#bar_chart-idea-3-generating-markdown-tables)
- [:art: Idea 4: Generating Visualizations](#art-idea-4-generating-visualizations)
- [:page_facing_up: Idea 5: Generating a table from CSV data](#page_facing_up-idea-5-generating-a-table-from-csv-data)
- [:star: Idea 5: Displaying API data as a list](#star-idea-5-displaying-api-data-as-a-list)
- [:crab: Idea 6: Run a Rust program](#crab-idea-6-run-a-rust-program)
- [:page_with_curl: License](#page_with_curl-license)
- [:handshake: Contributing](#handshake-contributing)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Python API](#python-api)
- [Examples](#examples)
- [Example 1: Simple code block](#example-1-simple-code-block)
- [Example 2: Multiple code blocks](#example-2-multiple-code-blocks)
- [Usage Ideas](#usage-ideas)
- [Idea 1: Continuous Integration with GitHub Actions](#idea-1-continuous-integration-with-github-actions)
- [Idea 2: Show command-line output](#idea-2-show-command-line-output)
- [Idea 3: Generating Markdown Tables](#idea-3-generating-markdown-tables)
- [Idea 4: Generating Visualizations](#idea-4-generating-visualizations)
- [Idea 5: Generating a table from CSV data](#idea-5-generating-a-table-from-csv-data)
- [Idea 6: Displaying API data as a list](#idea-6-displaying-api-data-as-a-list)
- [Idea 7: Run a Rust program](#idea-7-run-a-rust-program)
- [License](#license)
- [Contributing](#contributing)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- SECTION:installation:START -->
## :computer: Installation
## Installation

Install `markdown-code-runner` via pip:

Expand All @@ -69,7 +67,7 @@ pip install markdown-code-runner
<!-- SECTION:installation:END -->

<!-- SECTION:quick-start:START -->
## :rocket: Quick Start
## Quick Start

To get started with `markdown-code-runner`, follow these steps:

Expand Down Expand Up @@ -140,7 +138,7 @@ To get started with `markdown-code-runner`, follow these steps:
<!-- SECTION:quick-start:END -->

<!-- SECTION:python-api:START -->
## :snake: Python API
## Python API

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:

Expand All @@ -152,11 +150,11 @@ update_markdown_file("path/to/your/markdown_file.md")
<!-- SECTION:python-api:END -->

<!-- SECTION:examples:START -->
## :book: Examples
## Examples

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

### :star: Example 1: Simple code block
### Example 1: Simple code block
<!-- CODE:SKIP --> <!-- This is here otherwise the next example gets executed -->
```markdown
This is an example of a simple hidden code block:
Expand All @@ -183,7 +181,7 @@ Hello, world!
<!-- OUTPUT:END -->
```

### :star: Example 2: Multiple code blocks
### Example 2: Multiple code blocks
<!-- CODE:SKIP --> <!-- This is here otherwise the next example gets executed -->
```markdown
Here are two code blocks:
Expand Down Expand Up @@ -240,12 +238,12 @@ Hello again!
<!-- SECTION:examples:END -->

<!-- SECTION:usage-ideas:START -->
## :bulb: Usage Ideas
## Usage Ideas

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:

<!-- SECTION:github-actions:START -->
### :gear: Idea 1: Continuous Integration with GitHub Actions
### Idea 1: Continuous Integration with GitHub Actions

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.
Expand Down Expand Up @@ -335,7 +333,7 @@ jobs:
For more information on configuring GitHub Actions, check out the [official documentation](https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions).
<!-- SECTION:github-actions:END -->

### :computer: Idea 2: Show command-line output
### 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.

Expand Down Expand Up @@ -374,7 +372,7 @@ options:

<!-- OUTPUT:END -->

### :bar_chart: Idea 3: Generating Markdown Tables
### 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:

Expand Down Expand Up @@ -407,7 +405,7 @@ Which is rendered as:

<!-- OUTPUT:END -->

### :art: Idea 4: Generating Visualizations
### 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.

Expand Down Expand Up @@ -449,9 +447,9 @@ print(img_html)

<!-- OUTPUT:END -->

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

### :page_facing_up: Idea 5: Generating a table from CSV data
### 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.
Expand Down Expand Up @@ -479,7 +477,7 @@ Which is rendered as:

<!-- OUTPUT:END -->

### :star: Idea 5: Displaying API data as a list
### Idea 6: 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.
Expand Down Expand Up @@ -518,7 +516,7 @@ Which is rendered as:
<!-- OUTPUT:END -->


### :crab: Idea 6: Run a Rust program
### Idea 7: 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.

Expand Down Expand Up @@ -550,13 +548,13 @@ These are just a few examples of how you can use Markdown Code Runner to enhance
<!-- SECTION:usage-ideas:END -->

<!-- SECTION:license:START -->
## :page_with_curl: License
## License

`markdown-code-runner` is released under the [MIT License](https://opensource.org/licenses/MIT). Please include the LICENSE file when using this package in your project, and cite the original source.
<!-- SECTION:license:END -->

<!-- SECTION:contributing:START -->
## :handshake: Contributing
## Contributing

Contributions are welcome! To contribute, please follow these steps:

Expand Down