byron/termbook

A runner for `mdbooks` to keep your documentation tested.

termbook is a command-line tool to build mdbook's while executing codeblocks and collecting their output to become part of the mdbook.

This allows to write testable documentation for command-line interfaces.

It came to life for the documentation needs of share-secrets-safely.

Installation

Installation documentation can be found here.

Documentation

termbook uses termbook to document itself. Click here for more!

Roadmap

Add 'replace' support

Currently we can only append the output of programs. However, if there was 'replace', we can implement html converters, such as https://github.com/ivanceras/svgbobrus.

That way, diagrams can be written in text, either in the code-block, or in files which are then included via 'include-file'.

termbook renderer plugin programs for mdbook

Provide all renderers in termbook as standalone mdbook compatible plugin renderers, to allow easier integration with the mdbook binary.

Depends on rust-lang/mdBook#631

termbook preprocessor plugin programs for mdbook

Ideally, we don't have to wrap mdbook into termbook. Instead, there should be plugin-preprocessor support for mdbook, similar to what's already done for renderers.

Maintenance Guide

Making a new release

• Assure all documentation is up-to-date and tests are green
• Run cargo-clippy and fix all issues
• update the version in all Cargo.toml files and git commit
• run cargo publish for the library and the CLI
• run git tag -s <version>
• run git push --tags origin master
• update the asciinema docs
  • Set your terminal to a decent size
  • run make asciinema-no-upload
  • When happy with the result, run make asciinema-upload
  • visit the URL, configure the video, make it public, and copy the markdown link into the README file.
• update brew file
  • run make update-homebrew and commit the change

Documentation is updated on each push to master.

termbook's Issues

in crates.io the version remains 1.4.2

https://crates.io/search?q=termbook

A newline is missing when `include`ing a file

This can lead to markdown like this:

```
included-file without newline```

which turns out to be malformed markdown.

A solution could be to enforce a newline at the end of anything placed within code blocks.