Command Line Interface

markdown-code-runner provides a command-line interface for processing Markdown files.

Basic Usage

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

This will process the file in-place, executing all code blocks and updating the output sections.

Help Output

usage: markdown-code-runner [-h] [-o OUTPUT] [-d] [-v]
                            [--no-backtick-standardize] [-s] [-n]
                            input [input ...]

Automatically update Markdown files with code block output.

positional arguments:
  input                 Path(s) to the input Markdown file(s).

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)
  -s, --standardize     Post-process to standardize ALL code fences, removing
                        'markdown-code-runner' modifiers
  -n, --no-execute      Skip code execution entirely (useful with
                        --standardize for compatibility processing only)

Options

Input File (Required)

The path to the Markdown file to process.

markdown-code-runner README.md

Output File (`-o`, `--output`)

Write the result to a different file instead of modifying in-place.

markdown-code-runner README.md -o README_updated.md

Verbose Mode (`-d`, `--verbose`)

Enable verbose output to see each line being processed.

markdown-code-runner README.md --verbose

Disable Backtick Standardization (`--no-backtick-standardize`)

By default, when writing to a separate output file, the markdown-code-runner tag is removed from backtick code blocks. Use this flag to disable that behavior.

markdown-code-runner README.md -o output.md --no-backtick-standardize

Standardize All Code Fences (`-s`, `--standardize`)

Post-process the output to standardize ALL code fences, removing markdown-code-runner modifiers from language identifiers. This is useful for compatibility with markdown processors like mkdocs and pandoc that don't understand the python markdown-code-runner syntax.

markdown-code-runner README.md --standardize

This transforms code fences like:

```python
print('hello')
```

Into standard code fences:

```python
print('hello')
```

Skip Code Execution (`-n`, `--no-execute`)

Skip code execution entirely. This is useful when you only want to standardize code fences without running any code.

markdown-code-runner README.md --no-execute --standardize

This combination is particularly useful for:

Preparing files for external markdown processors
Converting files without re-running code blocks
Creating compatible output from existing processed files

Version (`-v`, `--version`)

Display the installed version.

markdown-code-runner --version

Examples

Process a Single File

markdown-code-runner docs/index.md

Process Multiple Files

for f in docs/*.md; do
    markdown-code-runner "$f"
done

Process All Files in a Directory

find docs -name "*.md" -exec markdown-code-runner {} \;

Process with Verbose Output

markdown-code-runner README.md --verbose