mdrip

mdrip serves rendered markdown to a browser, and allows one to paste code blocks directly to tmux for execution without use of a mouse.

It's a tool for markdown-based literate programming, and allows one to place markdown-based instructions under end-to-end testing.

mdrip, being a single-file Go-based executable, is easy to install.

Use it for Testing

For something to work with, use the following commands to download a busted Go tutorial:

repo=https://raw.githubusercontent.com/monopole/mdrip
curl -O $repo/master/assets/bustedGoTutorial.md

This markdown has code blocks showing how to write, compile and run a Go program in your TMPDIR.

Install mdrip, then extract blocks to stdout:

mdrip print bustedGoTutorial.md

Some code blocks in this markdown have labels; these are visible as HTML comments preceding the blocks in the raw markdown.

Use a label to extract a subset of blocks:

mdrip print --label goCommand bustedGoTutorial.md

Pipe the output of the above into /bin/bash -e to have the effect of a test, or for cleaner output try the test command:

mdrip test bustedGoTutorial.md
echo $?

The above command should show an error, and exit with non-zero status, because the tutorial has errors.

Fix the error:

cp bustedGoTutorial.md goTutorial.md

sed -i 's|badecho |echo |' goTutorial.md

Try the fix:

mdrip test goTutorial.md
echo $?

There's another error. Fix it:

sed -i 's|comment this|// comment this|' goTutorial.md

There are now two changes:

diff bustedGoTutorial.md goTutorial.md

Test the new file:

mdrip test goTutorial.md
echo $?

The return code should be zero.

You can run a block in your current shell to, say, set current environment variables as specified in the markdown:

eval "$(mdrip print --label setEnv goTutorial.md)"
echo $greeting

The upshot is that adding a line like

mdrip test --label {someLabel} {filePath}

to your CI/CD test framework covers the markdown code block execution path determined by that label.

The {filepath} argument defaults to your current directory (.), but it can be

• a path to a file,
• a path to a directory,
• a GitHub URL in the style gh:{user}/{repoName},
• or a particular file or a directory in the repo, e.g. gh:{user}/{repoName}/foo/bar.

Labels

Add labels to a code block by preceding the block with a one-line HTML comment, e.g:

<!-- @sayHello @mississippi @tutorial01 -->
```
echo hello
```

Labels are just words beginning with @ in the comment.

The first label on a block is slightly special in that it is treated as the block's name for various purposes. If no labels are present, a block name is generated for these purposes.

Use it for Tutorials

mdrip and tmux provide a handy way to develop and demonstrate command line procedures.

Render a markdown web app like this:

mdrip serve --port 8000 goTutorial.md

Visit it at localhost:8000.

Hit the n key for navigation tools. Hit ? to see all key controls.

The handy aspect is provided by tmux. If there's a running instance of tmux, the server will send code blocks to it when you hit Enter.

Fire up tmux, then try this README directly:

mdrip serve gh:monopole/mdrip/README.md

To see what using a full tree of markdown looks like, generate some markdown content with:

tmpdir=$(mktemp -d)
mdrip generatetestdata ${tmpdir}/mdTestData

then serve it:

mdrip serve ${tmpdir}/mdTestData

Literate Programming

mdrip encourages literate programming via markdown. It lets one run code that is embedded in explanatory content.

One can use here documents to incorporate any programming language into tested markdown - as in the busted Go tutorial discussed above. That tutorial could have covered C, C++, Rust, etc.

Place commands that the reader would want to execute directly (with no edits) in fenced code blocks.

In contrast, code-style text that is not intended for copy/paste execution, e.g. alternative commands with fake arguments or example output, should be in a fenced code block indented via a block quote. Block quotes are ignored by mdrip.