# 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”