https://github.com/khalidx/runbook

Executable markdown documents that you can run, template, and share!
https://github.com/khalidx/runbook

code-blocks markdown runbook runnable

Last synced: 4 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/khalidx/runbook
• Owner: khalidx
• License: mit
• Created: 2020-12-13T12:53:37.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2022-05-30T15:05:04.000Z (over 2 years ago)
• Last Synced: 2024-10-11T23:15:47.028Z (4 months ago)
• Topics: code-blocks, markdown, runbook, runnable
• Language: TypeScript
• Homepage:
• Size: 545 KB
• Stars: 40
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# runbook

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



[![npm package version badge](https://img.shields.io/npm/v/@khalidx/runbook.svg?style=flat-square)](https://www.npmjs.com/package/@khalidx/runbook)

[![GitHub last commit badge](https://img.shields.io/github/last-commit/khalidx/runbook.svg?style=flat-square)](https://github.com/khalidx/runbook/commits/main)

[![GitHub license badge](https://img.shields.io/github/license/khalidx/runbook.svg?style=flat-square)](https://github.com/khalidx/runbook/blob/main/LICENSE)

## quickstart

```bash "install"

npm install -g @khalidx/runbook

```

The [USAGE.md](./USAGE.md) file is a runnable markdown document. Check it for some usage examples.



## commands

[📂 ls](#runbook-ls) | [🚀 run](#runbook-run) | [🌐 serve](#runbook-serve) | [💁 help](#runbook-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.

````markdown

```bash "hello"

echo "Hello!"

```

```bash "two plus two"

echo $((2 + 2))

```

````

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

```text

document.md | hello

document.md | two plus two

```

Code blocks that are not annotated with a [supported runtime](USAGE.md#supported-runtimes) 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:

```bash

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](USAGE.md#supported-runtimes)

- 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](DEVELOPERS.md).