#command-line #productivity #utility #markdown #bash

bin+lib present

Interpolate the standard output of arbitrary shell scripts into your markdown files

6 releases

0.2.2 Jun 10, 2022
0.2.1 Jun 6, 2022
0.1.1 Feb 26, 2022
0.0.0 Jul 30, 2021

#1960 in Command line utilities

39 downloads per month

CC0 license

589 lines


CI crates.io docs.rs

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:

$ cargo install present

Below is the standard output of present --help, interpolated by the present binary itself!

present 0.2.2
Interpolate the standard output of arbitrary shell scripts into your markdown files

    present [OPTIONS] [PATH]

    <PATH>    A file or directory path to present.

    -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 = "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.

use std::path::PathBuf;

fn main() {
  let mut file = present::File::new(PathBuf::from("README.md")).unwrap();

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 running cargo 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

```present echo bar

```present echo bar
present foo.md --in-place --remove

```present echo bar


Prior Art

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.


~193K SLoC