termbook is a command-line tool and library designed to make your mdbook documentation executable.

Thus you are advised to use the mdbook command-line tool for everything that termbook does not support, as it is essentially nothing more than an mdbook clone with a custom preprocessor. The latter is not easily supported by mdbook just yet.

Features

termbook can do a few unique things for you

• execute codeblocks
  • This makes your documentation executable, with the output captured in their own codeblocks.
  • That way your documentation never goes out of sync with reality, and allows you to build documentation as part of your test suite.
• playback books to the terminal
  • This can be seen as 'eye-candy' generator, which is meant to be recorded with asciinema or similar tools.
  • Generate videos without ever having to type out commands yourself, and keep them consistent with your documentation.

termbook is a minimal clone of the mdbook command-line tool, and will only be required to build the final version of your book as it adds the needed mdbook preprocessor.

Installation

Via HomeBrew (OSX and Linux)

This is by far the most straight-forward way of installing termbook. Just execute the following code.

brew tap byron/termbook https://github.com/byron/termbook.git
brew install termbook

Via Github-Releases

At the github releases page you will find precompiled binaries for all common platforms.

Just decompress the respective archive and copy the termbook binary into your $PATH, usually this will be /usr/local/bin.

Windows is notably absent, but could be provided if there is demand.

Via Cargo

termbook can be installed via cargo only, which in turn can be obtained via rustup.

Then it's as easy as

cargo install termbook-cli

After the installation...

Now you should be able to run termbook:

termbook --help

termbook 1.4.6
Sebastian Thiel <byronimo@gmail.com>
`termbook` is a command-line tool to build `mdbook`'s while executing `bash` codeblocks and collecting their output to
become part of the `mdbook`.
              

USAGE:
    termbook [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    build          Build the `mdbook` compatible book in the current working directory or in the given location.
    completions    generate completions for supported shell
    help           Prints this message or the help of the given subcommand(s)
    play           Playback documentation by emulating a fast human typist.

Also have a look at the online documentation at https://byron.github.io/termbook

termbook build --help

Something worth mentioning explicitly is the support for chapter selectors, which allow you to limit the chapters where the preprocessor runs. This is useful if you run expensive commands and helps focussing on the chapter that you are currently editing.

Also have a look at the chapter about tags, as they are the bread-and-butter of termbook.

termbook play --help

This command will playback your book (or selected chapters) in a given typing speed, and in color given a modern terminal.

You can use it to record eye-candy ladden asciinema videos automatically and increase the perceived quality of the tool you are documenting.

termbook completions --help

Depending on your shell, the output of this subcommand goes to different spots on your disk. Please consult your $SHELLs documentation for more information.

The special feature termbook build adds to your capability is that it supports various tags that can be added to your codeblocks. Tags are executed in the order they occour in the codeblocks, and you can see them as statements which are executed left to right.

exec

The exec tag can be applied to any code-block which has a designated type, such as bash, fish or your-program. It will send the contents of the code-block to the program mentioned as type of the code-block, and expect it to succeed by default.

```bash,exec
echo 'this is being executed in bash'
```

By default exec expects the executed program to succeed (with exit-status 0), and the entire termbook build invocation will fail otherwise. This behaviour is useful to assert your documentation is still matching the program you document.

You can also indicate the desired exit status, which can be useful if your program is expected to fail.

```bash,exec=42
echo 'this should fail with a specific exit code' && exit 42
```

'prepare' and 'use'

It's useful to be able to use arbitrary snippets that are run prior to your exec code-block, which is useful to have shared code which prepares the playing field for the code you are about to run.

```bash,prepare=setup
function tb() { termbook; };
```

Now you can use the block in other prepare blocks, or in exec blocks. The former is useful for chaining prepare blocks.

```bash,use=setup,exec
tb
```

Here is the complete example as it will show up in your book:

function tb() { termbook; };

tb

USAGE:
    termbook [SUBCOMMAND]

hide

As you have seen in the previous example, it can be useful to hide certain code-blocks, especially those that are used solely for preparation. It's as easy as adding the hide tag.

```bash,hide,prepare=setup
function tb() { termbook; };
```

The previous example looks like this, when the prepare block is hidden:

tb

USAGE:
    termbook [SUBCOMMAND]

If hide is used on an exec block, itself and its output are hidden entirely.

```bash,hide,exec=1
termbook
```

include-file

The include-file tag is very powerful, as it allows you to keep your code in designated files, which then can be operated on by designated tools as well, greatly aiding testability.

As the name suggests, it will include the contents of a specified file into the codeblock the tag is used on. Files can be specified using absolute and relative paths. In the latter case, they are considered relative to the directory containing the mdbook.

Here is a simple example:

```bash,include-file=../directly-outdside-of-book.sh
# this comes first, the content of the file comes right after
```

Of course you can use this in conjunction with prepare blocks, allowing you to offload longer and more complex scripts into dedicated files.

```bash,include-file=some-complex-preparation.sh,prepare=complex,hide
```

Now you can use the complex block as preparation for another exec block:

```bash,use=complex,exec
echo 'this runs after the complex preamble was executed'
```

termbook-cli provides only the command-line interface for the implementation contained in the termbook library.

You can have a look at the library documentation for more information.