diff --git a/README.md b/README.md index bbce2ed..2ddef21 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# :rocket: Markdown Code Runner +# Markdown Code Runner -![](https://media.githubusercontent.com/media/basnijholt/nijho.lt/main/content/project/markdown-code-runner/featured.jpg) +Markdown Code Runner Logo `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. @@ -8,23 +8,21 @@ This package is particularly useful for maintaining Markdown files with embedded 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](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) -## :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)) -## :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. @@ -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. -## :books: Table of Contents +## Table of Contents -- [: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) -## :computer: Installation +## Installation Install `markdown-code-runner` via pip: @@ -69,7 +67,7 @@ pip install markdown-code-runner -## :rocket: Quick Start +## Quick Start To get started with `markdown-code-runner`, follow these steps: @@ -140,7 +138,7 @@ To get started with `markdown-code-runner`, follow these steps: -## :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: @@ -152,11 +150,11 @@ update_markdown_file("path/to/your/markdown_file.md") -## :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 ```markdown This is an example of a simple hidden code block: @@ -183,7 +181,7 @@ Hello, world! ``` -### :star: Example 2: Multiple code blocks +### Example 2: Multiple code blocks ```markdown Here are two code blocks: @@ -240,12 +238,12 @@ Hello again! -## :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: -### :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. @@ -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). -### :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. @@ -374,7 +372,7 @@ options: -### :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: @@ -407,7 +405,7 @@ Which is rendered as: -### :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. @@ -449,9 +447,9 @@ 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. +> **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. @@ -479,7 +477,7 @@ Which is rendered as: -### :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. @@ -518,7 +516,7 @@ Which is rendered as: -### :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. @@ -550,13 +548,13 @@ These are just a few examples of how you can use Markdown Code Runner to enhance -## :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. -## :handshake: Contributing +## Contributing Contributions are welcome! To contribute, please follow these steps: