mdup 0.2.1

Keep markdown files up-to-date.

mdup

Keep markdown files up-to-date by injecting code, script or command output between special blocks.

mdup does not depend on anything apart from Python stdlib.

Install

pip install mdup

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

Notes

• 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.

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.

Usage

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

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        Input file.
  -o OUTPUT, --output OUTPUT
                        Output file. If not specified, it will edit in place.

Running mdup -i <input.md> -o <output.md> will replace the contents between each block with the appropriate action as defined above. 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 cmdline 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.

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