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

Usage

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

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        input markdown file
  -o OUTPUT, --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 given the appropriate action kind (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 (CMD:poetry run mdup --help) -->
<!-- MDUP:END -->

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

Block definition

The blocks are defined using HTML comments.

Begin

<!-- MDUP:BEG ({KIND}:{CONTENTS}) -->

where {KIND} can be either:

• SRC: to include the contents of {CONTENTS}, e.g. from a path
• RUN: to execute the script from {CONTENTS} and inject its stdout in the block
• CMD: to execute the command from {CONTENTS} and inject its stdout in the block

For SRC and RUN commands, {CONTENTS} must be a path 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 (CMD:rm -rf /) -->
<!-- MDUP:END -->

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

Footnotes

1. Inspired by DavidWells/markdown-magic. ↩