mdup 0.2.3

Keep markdown files up-to-date.

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 [^1].

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

Running mdup -i <input.md> -o <output.md> will replace the contents between each block given the appropriate action kind (see details below). This means that 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:

<!-- MDUP:BEG (CMD:poetry run mdup --help) -->
<!-- MDUP:END -->

then running mdup -i README.md which executes poetry run mdup --help.

How does it work?

The blocks are defined using HTML comments. Specifically, the begin block is of the form:

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

where {KIND} can be either:

• SRC: to just 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, the {CONTENTS} must be a path, relative to the md file.

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

Examples

For examples, see tests.

⚠️ 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.

[^1]: Inspired by DavidWells/markdown-magic.