Scripting in markdown
I recently wrote yet another command-line utility in Rust called
that lets you interpolate the standard output of arbitrary commands
that get interpreted by the shell into a markdown file, and I
thought I’d share a bit about it here.
The main problem I kept running into that pushed me to write this tool was having to manually update the outputs of command line utility help messages in my project readme documents.
For instance, I wrote a command-line utility called
that lets you profile the startup-time for your installed vim
plugins and receive a nicely formatted output. In the readme
document I have a usage section that includes the output of calling
vp --help. Each time I make a version change, update
the description, or update the API – the result of calling
vp --help changes, which prompts me to update the
Instead of invoking the binary with the
piping the result to
pbcopy and then manually pasting
the chunk into the appropriate section within the readme myself, I
can now have
present do all of that for me.
Here’s how that looks like:
Include the command at the start of a fenced codeblock using the
## vim-profiler 🕒 ... ### Usage ```present cargo run -- --help ``` ...
presenton the markdown file
$ present --in-place --path readme.md
- View the modified document!
## vim-profiler 🕒 ... ### Usage ```cargo run -- --help vim-profiler 0.0.4 A vim profiling tool. USAGE: vp [FLAGS] [OPTIONS] FLAGS: -h, --help Prints help information -r, --reverse Display the plugin times in reverse order (fastest first) -s, --sys Show system plugins in the output -V, --version Prints version information -v, --verbose Add informative messages during program execution OPTIONS: -c, --command <command> The command to run, e.g vim or neovim [default: vim] -n, --count <count> The number of plugins to list in the output -e, --export <path> Export the results to a CSV file -f, --file <file> A file to open -i, --iter <iter> The number of iterations -p, --plot <path> Plot the data and save it to a SVG file -x, --precision <precision> Precision in the output ``` ...
In practice, I’ll add the command in a justfile
recipe that I invoke before I commit any changes, such as shown in
The project is still in its early stages of development, and there most certainly exists a few non-trivial bugs to be found and fixed.
Some things on the todo list, in no particular order, include:
Improve diff output in interactive mode
The project uses the
crate to help with diff output in interactive mode, but it can be
made nicer by taking advantage of additional features the crate has
Support same-line command interpolation
This isn’t that important, but it would be nice to support having backticks remain on the same line and have the command result get interpolated with the appropriate newlines. e.g
-> ```echo foo``` -> ```echo foo foo ```
Handle quotes as a single argument
This would let you actually write inline bash scripts, e.g
/bin/bash -c 'for i in *; do echo "$i"; done'. As of
right now, the program just splits the entire command string on
whitespace, which the shell doesn’t like in certain situations.
This however, for now, can be hacked around by simply including the
script in a justfile or makefile and invoking
just <name> or
make <name> within the markdown file.
Get rid of
The project uses the
crate to get full codeblock ranges within the source, and then
hackily turns them into two separate ranges (start, end) which
represent the starting and ending range of a single codeblock. This
could probably be done better, perhaps without depending on a
library for that initial step.
Overall, I get what I need out of the program as it is. Whether or not the aformentioned todo’s provide useful to someone else will most likely have a non-trivial amount of impact on my motiviation for getting them done.
I am compsci undergrad with a minor in mathematics @ mcgill university, programmer and rationalist. For fun I enjoy working on open-source projects, reading, and lifting weights.
Send me a message by email: liam [at] scalzulli.com or matrix: worse:matrix.org