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.
You'll need to have the Rust development environment installed and up to date.
Once it's installed, use cargo to install lfs:
shell {cmd=sh}
cargo install markdown-gem
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
shell {cmd=sh}
git clone git@github.com:murabi-io/markdown-gem.git
cd markdown-gem
cargo install --path .
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.
The attributes of the code chunk give the executor information on how to run the code, and filters define when not to run it.
| Attribute | Type | Optional/Default | Description |
|----------------|--------------------|------------------|---------------------------------------------------------------------------|
| cmd | string | no* | command name or path, e.g. sh, node and etc. |
| args | array of arguments | yes | command arguments |
| path | string | yes | PATH env variable for the command |
| asfile | boolean | yes/true | determines if markdown-gem should execute the code chunk as a file, default true |
| stdout | boolean | yes/true | determines if markdown-gem should display stdout of the code chunk, default true |
| allowwarnings | boolean | yes/true | determines if markdown-gem should allow warnings, default true |
| allowerrors** | boolean | yes/false | determines if markdown-gem should TODO: allow errors, default true |
| withsudo* | boolean | yes/false | tells markdown-gem to run the code chunk in sudo |
- * the implementation of the default commands by code chunk lang attribute will make this attribute optional
- ** the functionality for
allow_errorsis not there yet- * sudo support is not available yet, you can still execute
gemunder sudo, but keep in mind that all code chunks will inherit the sudo privileges
| Filter | Type | Optional/Default | Inclusive/Exclusive | Description |
|--------------|------------------|--------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sys | array of strings | yes/[] | inclusive | os system filter, possible values: linux, macos, ios, freebsd, dragonfly, netbsd, openbsd, solaris, android, windows |
| arch | array of strings | yes/[] | inclusive | system architecture filter, possible values: x86, x86_64, arm, aarch64, m68k, mips, mips64, powerpc, powerpc64, riscv64, s390x, sparc64 |
| linuxdistro | array of strings | yes/[] | inclusive | linux distro filter, e.g. arch, debian and etc, derived from linux release IDLIKE |
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.
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.