GitHub - terror/present: A script interpolation engine for markdown documents
source link: https://github.com/terror/present
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
present
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
USAGE:
present [OPTIONS] [PATH]
ARGS:
<PATH> A file or directory path to present.
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
Library
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();
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.
Examples
Below are a few examples showcasing what kind of command result interpolations
present
is currently able to handle.
present foo.md --in-place
|
|
|
present foo.md --in-place --remove
|
|
|
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK