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]

Sample Usages

Build the GitHub Pages document (this book):

mkbook build -i docs-src -o docs

Build the book, continually watching for changes and enabling auto-reloading in the browser so you can see the book update as you write:

mkbook watch -i docs-src -o docs --reload

Build a LaTeX version of the book, then compile it to a PDF and open it in evince:

mkdir build
mkbook build -i docs-src -o docs --latex build/book.tex
cd build
xelatex -shell-escape book.tex
xelatex -shell-escape book.tex
evince book.pdf