exec-commands − scan markdown files and execute console blocks
exec-commands is a utility to update command-line-tool examples embedded in markdown files. It scans .md-suffixed files in a directory, extracts all code blocks with a console attribute, executes each $-prefixed line in a shell, and embeds the result right below the line.
Note: Please use exec-commands inside a sandbox. exec-command itself doesn't have any mechanism to protect the host environment from malicious commands embedded in markdown files.
Options
$ exec-commands --help
exec-commands 0.0.1
Hajime Suzuki ([email protected])
scan markdown files and execute `console` blocks
USAGE:
exec-commands [OPTIONS] [INPUTS]...
ARGS:
<INPUTS>... Input markdown files (overrides config and glob)
OPTIONS:
-c, --config <CONFIG> Path to config file (it always loads .exec-commands.yaml if exists)
-d, --diff Take diff between original and updated contents
-e, --extension <EXT> Extension of files to scan (when no file specified by config or
argument) [default: md]
-h, --help Print help information
--path <PATH> Additional paths to find commands (colon-delimited)
--pwd <PWD> Directory where commands are executed
-r, --reverse Remove existing output lines
-V, --version Print version information
Configuration file format
It takes configuration in the yaml format. Below is an example and description of the fields.
# `inputs` is an array of input files.
inputs:
- README.md
- doc/**/*.md # wildcard allowed; `**` matches directories with zero or more depths.
# `pwd` specifies the directory to run commands
pwd: "test"
# `path` is additional directories to search commands; extends the PATH environment variable.
path: "target/debug:$HOME/.cargo/bin"
# `alt` is a list of command substitutions. when it finds `raw`, it executes `alt` instead.
alt:
- raw: "some-command --option-that-takes-long-time"
alt: "another-command --with-the-fastest-option"
- raw: "one-more-command --that-takes-user-input"
alt: "alternative-command --that-runs-without-user-input"
# it executes a sequence of commands before and after every block and file.
hooks:
pre_block:
- "git clean -f -d"
- "git checkout HEAD ."
post_block:
- ":"
pre_file:
- ":"
post_file:
- "git clean -f -d"
- "git checkout HEAD ."
Copyright and License
2022, Hajime Suzuki. Licensed under MIT.
6 Feb 17, 2023
3 Dec 21, 2022
5 Jul 25, 2023
3 Nov 28, 2023
15 Dec 27, 2022
369 Jan 2, 2023
94 Apr 12, 2023
9 Dec 26, 2022
13 Jun 6, 2023
293 Jan 6, 2023
6 Jun 3, 2023
3 Sep 9, 2023
5 Oct 26, 2023
11.6k Jan 4, 2023
308 Jan 1, 2023
5 Apr 25, 2023
104 Oct 7, 2023
11 Jan 25, 2023