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 1.
mdup
does not depend on anything apart from Python stdlib.
pip install mdup
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.
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 pathRUN
: to execute the script from{CONTENTS}
and inject its stdout in the blockCMD
: 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.
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.
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
-
Inspired by DavidWells/markdown-magic. ↩