runbook

Executable markdown documents that you can run, template, and share!

quickstart

npm install -g @khalidx/runbook

The USAGE.md file is a runnable markdown document. Check it for some usage examples.

commands

📂 ls | 🚀 run | 🌐 serve | 💁 help

📂 runbook ls

Lists all commands found in documents in the current directory.

It discovers files that end in .md, parses them, and finds all fenced code blocks in the file.

It returns a list of "commands", which are any fenced code blocks that are annotated with a language + a name. Check out the examples below.

```bash "hello"
echo "Hello!"
```

```bash "two plus two"
echo $((2 + 2))
```

Running runbook ls would output a command list like the following:

document.md | hello
document.md | two plus two

Code blocks that are not annotated with a supported runtime and a quoted name will be ignored by runbook.

🚀 runbook run

Runs the specified command.

The command must be specified in a markdown document in the current directory.

For example, to run the "hello" command shown above, type:

runbook run hello

🌐 runbook serve

Starts up a server and automatically opens the browser to a page that displays all discovered documentation and commands.

💁 runbook help

Shows what you can do with the runbook CLI.

features

• define and document reusable commands in your favorite language, with many currently supported
• list all commands found in markdown documents in the current directory with runbook ls
• run a specific command from a document with runbook run
• commands can be templated with arguments using handlebars {{ }} syntax
• commands can be overloaded
• command suggestions are returned if input doesn't match a command
• commands are checked for uniqueness (name + arity + args)
• commands written in bash can call other commands
• commands can be referenced from external files, rather than embedded
• serve all discovered documentation and commands with runbook serve
• debug logs are written to ~/.runbook/logs/

contributing

Open a GitHub issue to report a bug or request a feature!

For developing the runbook application itself, check this out.