present is a tool that lets you interpolate the standard output of arbitrary scripts that get interpreted by the shell into your markdown documents.
Its aim is to provide a nice way to automatically update sections of your markdown documents that might be the standard output of a command, such as command-line utility help outputs or benchmarks.
Below is a short demo showcasing the main functionality of the program.
You can install the present
command-line utility with the rust package manager
cargo:
bash
$ cargo install present
Below is the standard output of present --help
, interpolated by the present
binary itself!
```present cargo run -- --help present 0.2.2 Interpolate the standard output of arbitrary shell scripts into your markdown files
USAGE: present [OPTIONS] [PATH]
ARGS:
OPTIONS: -h, --help Print help information --in-place Modify documents in place. --interactive Interactively present markdown documents. --pretty Pretty print documents to the terminal. --recursive Recursively present markdown documents. --remove Remove commands within markdown documents. -V, --version Print version information ```
present
can be used as a library by adding this line to the [dependencies]
section in Cargo.toml
:
present ./bin/get_version
present = "0.2.2"
With present
, you can create a File
struct by pointing it to a path. This
will parse all codeblocks with the present
prefix, and add them as commands to
the struct. From there, you can present the file by using the File::present
function, which will modify the internal content. From there, you can use the
File::print
or File::save
functions to print the presented document to
stdout or save it back to the original file.
```rust use std::path::PathBuf;
fn main() { let mut file = present::File::new(PathBuf::from("README.md")).unwrap(); file.present().unwrap(); file.save(); } ```
The above snippet is tested with rustdoc. A really cool side effect of this, is that the test loads the README itself, and runs
present
over it.present
is also used throughout the README (to get help-text and version numbers), which means that when runningcargo test
, the README gets automatically updated.
You can read more about using the library on docs.rs.
Below are a few examples showcasing what kind of command result interpolations
present
is currently able to handle.
present foo.md --in-place
|
````ignore foo ```present echo bar ``` ```` | ````ignore foo ```present echo bar bar ``` ```` |
present foo.md --in-place --remove
|
````ignore foo ```present echo bar ``` ```` | ````ignore foo bar ```` |
This project is loosely inspired by Cog
, the
code generation tool. However, as mentioned above, this project's main target is
markdown documents that may benefit to have certain sections automatically
updated, due to being the result of a command invocation.