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]
Next chapter: “Markdown”