5 releases (breaking)
0.5.0 | Jan 30, 2023 |
---|---|
0.4.0 | Dec 21, 2022 |
0.3.0 | Dec 21, 2022 |
0.2.0 | Jul 9, 2022 |
0.1.0 | Jul 8, 2022 |
#491 in Text processing
172 downloads per month
22KB
156 lines
mdbook-cmdrun
This is a preprocessor for the rust-lang mdbook project. This allows to run arbitrary (shell) commands and include the output of these commands within the markdown file.
Getting started
cargo install mdbook-cmdrun
You also have to activate the preprocessor, put this in your book.toml
file:
[preprocessor.cmdrun]
How to
Let's say we have these two files:
Markdown file: file.md
# Title
<!-- cmdrun seq 1 10 -->
<!-- cmdrun python3 script.py -->
Python file: script.py
def main():
print("## Generated subtitle")
print(" This comes from the script.py file")
print(" Since I'm at in a scripting language,")
print(" I can compute whatever I want")
if __name__ == "__main__":
main()
The preprocessor will call seq then python3, and will produce the resulting file:
# Title
1
2
3
4
5
6
7
8
9
10
## Generated subtitle
This comes from the script.py file
Since I'm at in a scripting language,
I can compute whatever I want
Details
When the pattern <!-- cmdrun $1 -->\n
is encountered, the command $1
will be run using the shell sh
like this: sh -c $1
.
Also the working directory is the directory where the pattern was found (not root).
The command invoked must take no inputs (stdin is not used), but a list of command lines arguments and must produce output in stdout, stderr is ignored.
WARNING: This method only works with any system that has a shell sh
that rust can find. Windows is not supported for now, see here for more.
Examples
The following is valid:
<!-- cmdrun python3 generate_table.py -->
```rust
<!-- cmdrun cat program.rs -->
```
```diff
<!-- cmdrun diff a.rs b.rs -->
```
```console
<!-- cmdrun ls -l . -->
```
Some more examples are implemented, and are used as regression tests. You can find them here. At the moment of writing, there are examples using:
- Shell
- Bash script
- Python3
- Rust
Current version: 0.5.0
License: MIT
Dependencies
~9–40MB
~685K SLoC