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.2.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
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]