mdbook-cmdrun 0.4.0

mdbook preprocessor to run arbitrary commands
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

[![Workflow Status](https://github.com/FauconFan/mdbook-cmdrun/actions/workflows/main.yml/badge.svg)](https://github.com/FauconFan/mdbook-cmdrun/actions?query=workflow%3A%22main%22)
![Crates.io](https://img.shields.io/crates/l/mdbook-cmdrun)

# mdbook-cmdrun

This is a preprocessor for the [rust-lang mdbook](https://github.com/rust-lang/mdBook) project. This allows to run arbitrary (shell) commands and include the output of these commands within the markdown file.

## Getting started

```sh
cargo install mdbook-cmdrun
```

You also have to activate the preprocessor, put this in your `book.toml` file:
```toml
[preprocessor.cmdrun]
```

## How to

Let's say we have these two files:

Markdown file: file.md
```markdown
# Title

<!-- cmdrun seq 1 10 -->

<!-- cmdrun python3 script.py -->

```

Python file: script.py
```python
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:

```markdown
# 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).
Any command that takes no input, but a list of command lines arguments and produce output in stdout, stderr is ignored.

## Examples

The following is valid:

````markdown

<!-- 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](https://github.com/FauconFan/mdbook-cmdrun/tree/master/tests/regression/).
At the moment of writing, there are examples using:
- Shell
- Bash script
- Python3
- Rust


Current version: 0.4.0  
License: MIT