Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ctsrc/mdrun
Runs command-line pipelines embedded in Markdown and CommonMark documents. Keeps your authored docs up to date. Even usable as an alternative to IPython notebooks.
https://github.com/ctsrc/mdrun
abstract-syntax-tree ast commonmark computer-science data-science devops iac infrastructure-as-code markdown qa quality-assurance software-development software-engineering sre technical-writing writing-tool
Last synced: 16 days ago
JSON representation
Runs command-line pipelines embedded in Markdown and CommonMark documents. Keeps your authored docs up to date. Even usable as an alternative to IPython notebooks.
- Host: GitHub
- URL: https://github.com/ctsrc/mdrun
- Owner: ctsrc
- License: isc
- Created: 2021-10-01T09:25:49.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2021-10-01T10:52:47.000Z (over 3 years ago)
- Last Synced: 2025-01-01T16:38:55.505Z (23 days ago)
- Topics: abstract-syntax-tree, ast, commonmark, computer-science, data-science, devops, iac, infrastructure-as-code, markdown, qa, quality-assurance, software-development, software-engineering, sre, technical-writing, writing-tool
- Language: Shell
- Homepage:
- Size: 33.2 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mdrun
[](https://crates.io/crates/mdrun) [](https://docs.rs/mdrun/)
Runs command-line pipelines embedded in Markdown and CommonMark documents.
Keeps the output of shell commands in your README.md
and other documents up to date.
Automatically rewrites the table of contents for your README.md.
Usable as an alternative to IPython notebooks.
Vaguely reminiscient of Knuth's computer programming system "Web"
with its programs TANGLE and WEAVE, but at the same time not.
## Work in progress
This tool is not yet ready for use, as at present time
no code for it has yet been written.
## Table of contents
Table of contents will be added as soon as `mdrun` is able to generate it.
## Introduction
`mdrun` is a tool that reads Markdown and CommonMark documents and:
- Runs shell commands from one or more specified sections of your document.
- Captures the output of said shell commands.
- Inserts the output of the shell commands into the document.
- Updates the output of the shell commands in the document.
Additionally, it performs the following tasks:
- Generates a table of contents for your document.
- Updates the table of contents in your document.
## Dogfooding
We wrote this tool to scratch an itch, and we use it ourselves.
Both in other projects, and on the very README you are presently reading.
(Also, when I say "we" I actually mean "I", because there is only me working
on this as of yet. Contributions are welcome though, as long as they stick to
the essence of the project. So perhaps one day it really will be "we".)
## Use cases
The foremost usecase for `mdrun` lies in keeping documentation up to date,
by capturing and updating the output of shell commands that your docmuents
contain.
Aside from this, one of many other possible use cases include using `mdrun`
with a Markdown or CommonMark document in the style of what IPython provides
when you choose to "Run all cells" on an IPython notebook. Albeit more simple
and less interactive compared to IPython of course. Simpler and less
interactive for the time being, at least.
## Usage
Since one might not want to execute all commands in any given document,
the tool requires that you specify which section(s) of the document
to run shell commands from. By default, no commands will be executed
unless sections are specified, and furthermore, only the commands
that belong to the section itself, and not any commands inside of
any subsections will be executed.
Additionally, for safety and convenience, `mdrun` will only execute
fenced commands that satisfy the following conditions:
1. The code block containing the command is fenced and has an info string
indicating which shell the command is to be run in.
2. The aforementioned info string has a value corresponding to either
of the following: `zsh`, `fish`, `bash`, `sh`, `ksh`, `tcsh` or `csh`.
3. The code block containing the command is immediatelly followed
by a code block that has an info string with a value of `text`.
As such, assuming `mdrun` has been installed to a directory that is
in your `$PATH`, and you were to run the following command in this
directory, specifying that `mdrun` run on the section titled "Usage"
of this README:
```zsh
mdrun -s Usage README.md
```
And further assuming that you have `zsh` installed on your system,
then you will find that the following commands will execute and
the output will be updated correspondingly.
```zsh
date +%s
```
```text
```
```zsh
uname -a
```
```text
```
Whereas the following command will not be executed, because there is no
corresponding fenced code block with info string `text` immediatelly
following it.
```zsh
echo This command is not executed.
```
Likewise, the following command will not be executed either, because
the info string for the command code block has a value that is different
from the set of accepted values for the info string of a command code block:
```python3
print("Hello from Python 3.")
```
```text
```
Although... Python may eventually be considered to be in scope. So in that case
we'll have to come up with another example instead.
This one may be a safer bet for something that will probably remain
considered out of scope:
```sql
select current_date;
```
```text
```
Since in order for that command to really make sense, we'd at the very least
need to know which sql client to use (PostgreSQL here), and usually we'd need
to know which database to run the sql command on etc.
Either way, in both the case of Python 3 and any command-line capable sql client,
if you wanted to run commands and capture output you could specify a shell command
that invokes the tool in question.
So for example Python 3:
```zsh
python3 -c "print('Hello from Python 3.')"
```
```text
```
and a multi-line Python 3 example:
```zsh
python3 <` and
`--toc-depth-max ` arguments.
For example:
```zsh
mdrun --toc-depth-min 1 --toc-depth-max 6 --toc-only README.md
```
### Verbosity
By default, `mdrun` runs with a verbosity level of "info", which causes it
to print out the commands that are currently being executed.
You can reduce the verbosity level to "warn" which will only print warnings and errors
by supplying the `--silent` flag once or its alias `-s` once.
You can reduce the verbosity level to "errors" which will only print errors
by supplying the `-s` flag twice; `-ss`.
You can silence `mdrun` completely by supplying the `-s` flag thrice; `-sss`.
In this mode nothing is printed by the tool, aside from panics that may be printed
by the Rust runtime. This verbosity level -- or rather perhaps, quietness level --
may be useful in certain scripting settings. The `mdrun` command will of course
still exit with an appropiate exit status indicating whether it was able to
successfully complete its tasks or not.
### Synopsis (quick help) and version
A synopsis of how to invoke `mdrun` is available by running the `mdrun` command
with the `--help` flag or its alias `-h`:
```zsh
mdrun -h
```
```text
```
You can retrieve version information by running the `mdrun` command with
the `--version` flag.
```zsh
mdrun --version
```
```text
```
## Installation
### Option 1: Via the package manager for your operating system
This option is not yet available, but we hope to see this tool available
in the following package managers eventually:
- Homebrew for macOS
- Official apt repositories for Ubuntu, KDE Neon and Debian
- Arch Linux AUR
- FreeBSD ports
- and more...
### Option 2: Download precompiled binaries via the GitHub releases page
Not yet available but will be soonish.
### Option 3: Via crates.io using the Rust development environment tool `cargo`
1. Install the Rust development environment, if you haven't done so already:
```zsh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
2. Install mdrun:
```zsh
cargo install mdrun
```
## Acknowledgements
This tool would not be possible without the awesome CommonMark Markdown parser
[comrak](https://github.com/kivikakk/comrak).
## Contributing
If you have a feature that you'd like to implement, or a bug that you would
like to fix, please file an issue so that we can discuss it and if what you
have in mind is in line with the goals and scope of this project then I will
give you the go-ahead signal and you can then code it up and submit a
pull-request that we can discuss further.
## ⭐ Star, share, like, subscribe ;) ⭐
If you enjoy this project please remember to star it on GitHub.
And feel free to tell some friends, colleagues or your family about it too :)