Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/FauconFan/mdbook-cmdrun
A mdbook preprocessor for runnning arbitrary (shell) commands in a markdown file
https://github.com/FauconFan/mdbook-cmdrun
Last synced: about 2 months ago
JSON representation
A mdbook preprocessor for runnning arbitrary (shell) commands in a markdown file
- Host: GitHub
- URL: https://github.com/FauconFan/mdbook-cmdrun
- Owner: FauconFan
- License: mit
- Created: 2022-07-07T16:09:18.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-03-12T16:56:24.000Z (7 months ago)
- Last Synced: 2024-07-24T21:12:22.062Z (2 months ago)
- Language: Rust
- Homepage:
- Size: 102 KB
- Stars: 28
- Watchers: 2
- Forks: 6
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/FauconFan/mdbook-cmdrun/actions?query=workflow%3A%22main%22)
# 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
```
Python file: script.py
```python
def main():
print("## Generated subtitle")
print(" This comes from the script.py file")
print(" Since I'm 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 in a scripting language,
I can compute whatever I want
```
## Details
When the pattern `\n` or `` 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.
As of July 2023, mdbook-cmdrun runs on Windows platforms using the `cmd` shell!
## Examples
The following is valid:
````markdown
```rust
```
```diff
```
```console
```
## Example of inline use inside a table
````markdown
Item | Price | # In stock
---|---|---
Juicy Apples | | **
Bananas | ** |
````
Which gets rendered as:
````markdown
Item | Price | # In stock
---|---|---
Juicy Apples | 1.99 | *7*
Bananas | *1.89* | 5234
````
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
- Batch script
- Python3
- Node
- Rust
## Contributors
I would like to thank [@exsjabe](https://github.com/exsjabe) for his valuable help with integrating Windows support and inline cmdrun calls.
Current version: 0.6.0
License: MIT