#mdbook #preprocessor #runcmd

bin+lib mdbook-cmdrun

mdbook preprocessor to run arbitrary commands

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

Download history 6/week @ 2022-12-01 3/week @ 2022-12-08 24/week @ 2022-12-15 41/week @ 2022-12-22 4/week @ 2022-12-29 17/week @ 2023-01-05 4/week @ 2023-01-12 4/week @ 2023-01-19 30/week @ 2023-01-26 14/week @ 2023-02-02 13/week @ 2023-02-09 17/week @ 2023-02-16 7/week @ 2023-02-23 14/week @ 2023-03-02 72/week @ 2023-03-09 78/week @ 2023-03-16

172 downloads per month

MIT license

22KB
156 lines

Workflow Status Crates.io

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