mdup

mdup is a command-line tool for keeping markdown files up-to-date by injecting code, script or command output between special blocks. One immediate use case is keeping documentation up-to-date without having to manually update markdown files with info from code snippets, scripts or command outputs ¹.

mdup does not depend on anything apart from Python stdlib.

Install

pip install mdup

or easier usage via uv:

uv tool run mdup

Usage

usage: mdup [-h] -i INPUT [-o OUTPUT] [-v]

options:
  -h, --help           show this help message and exit
  -i, --input INPUT    input markdown file
  -o, --output OUTPUT  output markdown file; if not specified, the input file
                       will be edited in place
  -v, --version        show program's version number and exit

mdup will replace the contents between each block with the command output (see details below). You can keep files up-to-date by simply rerunning mdup.

Omitting the -o option will edit the file in-place.

For example, the command-line usage block above is automatically generated by defining the following block in the README.md:

<!-- MDUP:BEG uv run mdup --help -->
<!-- MDUP:END -->

then running mdup -i README.md which executes uv run mdup --help and injects the output inside the block.

Block definition

The blocks are defined using HTML comments.

Begin

<!-- MDUP:BEG (command) (; pre) -->

Examples:

<!-- MDUP:BEG cat ./mdup.py ; py -->
<!-- MDUP:BEG ls -lh -->

If you want to add a markdown language tag (pre, like py in the first example), then it must follow the command, separated by a semicolon.

Paths are relative to the markdown file containing the blocks.

End

<!-- MDUP:END -->

The blocks must be defined as the sole contents of the line, i.e. matching ^ and $ anchors.

Examples

For examples, see tests.

One real-world use case is my Advent of Code README.md, in which I use mdup to automatically update year progress badges.

⚠️ Disclaimer

I created this tool primarily to meet my own needs -- it's very simple and ad-hoc. While I don't anticipate it gaining too much adoption, always beware when running mdup on markdown files of unknown origin (which can be malicious), e.g.:

<!-- MDUP:BEG rm -rf / -->
<!-- MDUP:END -->

This tool should only be used for simple tasks, e.g. keeping simple documentation up-to-date.