markdown-gem
| Crates.io | markdown-gem |
| lib.rs | markdown-gem |
| version | 0.1.0 |
| source | src |
| created_at | 2022-11-28 10:47:54.410494 |
| updated_at | 2022-11-29 12:17:20.283147 |
| description | Markdown code chunk runner and renderer |
| homepage | https://github.com/murabi-io/markdown-gem |
| repository | https://github.com/murabi-io/markdown-gem |
| max_upload_size | |
| id | 724361 |
| size | 3,787,050 |
Timur Khamrakulov (htimur)
documentation
README
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
| 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 |
| as_file | 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 |
| allow_warnings | boolean | yes/true | determines if markdown-gem should allow warnings, default true |
| allow_errors** | boolean | yes/false | determines if markdown-gem should TODO: allow errors, default true |
| with_sudo*** | 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
Available filters
| 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 |
| linux_distro | array of strings | yes/[] | inclusive | linux distro filter, e.g. arch, debian and etc, derived from linux release ID_LIKE |
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.