markdown-code-runner

A Rust implementation of markdown-code-runner - automatically update Markdown files with code block output.

Installation

cargo install markdown-code-runner

Or build from source:

git clone https://github.com/basnijholt/markdown-code-runner-rs
cd markdown-code-runner-rs
cargo install --path .

Usage

markdown-code-runner [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Path to the input Markdown file

Options:
  -o, --output <OUTPUT>          Path to the output Markdown file (default: overwrite input file)
  -d, --verbose                  Enable verbose/debug mode
      --no-backtick-standardize  Disable backtick standardization
  -s, --standardize              Post-process to standardize ALL code fences
  -n, --no-execute               Skip code execution entirely
  -h, --help                     Print help
  -V, --version                  Print version

Markdown Syntax

Backtick Code Blocks

Add markdown-code-runner after the language identifier to mark a code block for execution:

```python markdown-code-runner
print('Hello, world!')
```
<!-- OUTPUT:START -->
This will be replaced by the output.
<!-- OUTPUT:END -->

Hidden Code Blocks (HTML Comments)

Use HTML comments to hide the code while still executing it:

<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This will be replaced by the output.
<!-- OUTPUT:END -->

For Bash:

<!-- CODE:BASH:START -->
<!-- echo "Hello from bash!" -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This will be replaced by the output.
<!-- OUTPUT:END -->

Skip Marker

Use <!-- CODE:SKIP --> to prevent execution of the next code block:

<!-- CODE:SKIP -->
```python markdown-code-runner
print('This will not be executed')
```
<!-- OUTPUT:START -->
This output will be preserved.
<!-- OUTPUT:END -->

Write to File

Use the filename= option to write code to a file instead of executing:

```rust markdown-code-runner filename=example.rs
fn main() {
    println!("Hello, Rust!");
}
```
<!-- OUTPUT:START -->
<!-- OUTPUT:END -->

Variable Persistence

Variables defined in Python code blocks are shared across all subsequent Python blocks in the same file:

```python markdown-code-runner
x = 42
print(x)
```
<!-- OUTPUT:START -->
42
<!-- OUTPUT:END -->

```python markdown-code-runner
print(x * 2)
```
<!-- OUTPUT:START -->
84
<!-- OUTPUT:END -->

Indented Code Blocks

Code blocks in list items or other indented contexts are supported:

1. Example:

    ```python markdown-code-runner
    print('indented')
    ```
    <!-- OUTPUT:START -->
    indented
    <!-- OUTPUT:END -->

License

MIT License - see LICENSE for details.

Related

• markdown-code-runner - The original Python implementation