markdown-gem, a.k.a gem - markdown code chunks executor

Inspired by R Markdown code chunks, but for any code.

Our goal is to make markdown documentation, examples, instructions, or anything related to the code in your MD files - provable, easily maintainable, and integrate it into your CI pipelines.

Install

From crates.io

You'll need to have the Rust development environment installed and up to date.

Once it's installed, use cargo to install lfs:

cargo install markdown-gem

From source

You'll need to have the Rust development environment installed.

Fetch the murabi-io/markdown-gem repository, move to the markdown-gem directory, then run

git clone git@github.com:murabi-io/markdown-gem.git
cd markdown-gem
cargo install --path .

Why use markdown-gem

• automate and document at the same time
• maintain your documentation and make sure the examples are working
• improve your user experience

Code chunks

A code chunk is a code that is part of your markdown and you want it executed, e.g.

```sh {sys=[linux], linux_distro=[debian]}
apt install ...
```

The code chunk above defines a shell script to install something using apt, and it'll run only on Linux systems of the Debian family. The metadata of the code chunk is ignored by most renderers and users will only see the shell code containing the apt... part.

Attributes and filters

The attributes of the code chunk give the executor information on how to run the code, and filters define when not to run it.

Available attributes

• * the implementation of the default commands by code chunk lang attribute will make this attribute optional
• ** the functionality for allow_errors is not there yet
• *** sudo support is not available yet, you can still execute gem under sudo, but keep in mind that all code chunks will inherit the sudo privileges

Available filters

Security

The code chunks are executed on the host machine without any pre-checks in a form provided in the markdown documents. The execution is done through tokio::process::Command and the detailed documentation can be found here: tokio::process::Command.

You should perceive running code chunks as running any other shell script, with all the inherent dangers.

License and Acknowledgements

The implementation is based on termimad and few other projects. I would like to thank Denys Séguret and crossterm-rs for their work and the existing open source code I used as inspiration.