Introduction
mkbook is my simpler alternative to mdbook which is a great tool, but for which I really dislike some of the decisions they took, such as relying on javascript for highlighting and navigation, and including a lot of bells and whistles such as javascript-based search.
This tool aims to work somewhat similarly to mdbook, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.
If you’re not familiar with mdbook, mkbook is a tool to convert a collection of Markdown files into a static website / book which can be published online. It was created to help me write documentation with minimum fuss while presenting it in an easy-to-consume manner.
Command-line Interface
mkbook may be installed using Cargo (cargo install --force --path .
in the mkbook repo directory), and after that it presents a command-line interface:
$ mkbook mkbook 0.3.0 Kenton Hamaluik <kenton@hamaluik.ca> USAGE: mkbook [SUBCOMMAND] FLAGS: -h, --help Prints help information -V, --version Prints version information SUBCOMMANDS: build build the book help Prints this message or the help of the given subcommand(s) init initialize a mkbook directory tree watch build the book and continually rebuild whenever the source changes
The Init Command
The init command is a tool to help you get started, and will create an initial README.md
file and a stub of your first chapter.
$ mkbook init --help mkbook-init initialize a mkbook directory tree USAGE: mkbook init [OPTIONS] FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -d, --directory <directory> an optional directory to initialize into [default: src]
The Build Command
The build command is the primary command for mkbook, and is responsible for taking the .md
files and building the resulting website.
$ mkbook build --help mkbook-build build the book USAGE: mkbook build [OPTIONS] FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -i, --in <in> an optional directory to take the book sources from [default: src] -o, --out <out> an optional directory to render the contents into [default: book]
The Watch Command
The watch command is basically the same as the build
command, however after building it continues to monitor the source directory and if any changes are made (a file is saved, renamed, removed, created, etc), the entire book is re-built. In the future, this will hopefully be smarter but for now it just the whole thing at once. Stop watching using Ctrl+C or sending SIGINT
.
$ mkbook build --help mkbook-watch build the book and continually rebuild whenever the source changes USAGE: mkbook watch [OPTIONS] FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -i, --in <in> an optional directory to take the book sources from [default: src] -o, --out <out> an optional directory to render the contents into [default: book]