Skip to content

Getting Started

This guide will help you install and start using markdown-code-runner in minutes.

Installation

Install markdown-code-runner via pip:

pip install markdown-code-runner

You can also install with uv:

uv pip install markdown-code-runner

Or as a tool:

uv tool install markdown-code-runner

Quick Start

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

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

  2. Run markdown-code-runner on your Markdown file:

    markdown-code-runner /path/to/your/markdown_file.md

  3. The output of the code block will be automatically executed and inserted between the output markers.

Next Steps