2018-12-09

The Advent of Void: Day 9: mdbook

Writing documentation often isn’t as much fun as writing code, but in many cases its more important than writing code. Increasingly common it is expected for project documentation to be available online. A well-known tool for converting markdown to html is gitbook, however gitbook is written in nodejs, is slow, and has lots of edge cases where it can break in obscure ways.

Similar to the OpenBSD community, the Rust community likes to re-implement tools at a higher standard. To replace gitbook, the Rust community has written an excellent tool called mdbook.

When you create a new mdbook, a small wizard guides you through the process:

$ mdbook init

Do you want a .gitignore to be created? (y/n)
n
What title would you like to give the book?
Advent of Void
2018-12-08 22:09:54 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

The resulting stub book looks like this:

.
├── book
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

2 directories, 3 files

If we were to render this book with mdbook build then the book/ subdirectory would be populated.

$ mdbook build
2018-12-08 22:13:08 [INFO] (mdbook::book): Book building has started
2018-12-08 22:13:08 [INFO] (mdbook::book): Running the html backend
$ tree .
.
├── book
│   ├── FontAwesome
│   │   ├── css
│   │   │   └── font-awesome.css
│   │   └── fonts
│   │       ├── FontAwesome.ttf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── ayu-highlight.css
│   ├── book.js
│   ├── chapter_1.html
│   ├── clipboard.min.js
│   ├── css
│   │   ├── chrome.css
│   │   ├── general.css
│   │   ├── print.css
│   │   └── variables.css
│   ├── elasticlunr.min.js
│   ├── favicon.png
│   ├── highlight.css
│   ├── highlight.js
│   ├── index.html
│   ├── mark.min.js
│   ├── print.html
│   ├── searcher.js
│   ├── searchindex.js
│   ├── searchindex.json
│   └── tomorrow-night.css
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

6 directories, 29 files

The book is now ready for serving and we could copy the book/ subdirectory anywhere we please for serving, even an AWS S3 bucket to be served as a fully static bundle.

Of course, all of the files in book/ are driven by the source files in src/. The SUMMARY.md file is a listing of the structure of the book, and the chapter_1.md is a stub for a single chapter within the book.

All of these files are easy to read markdown. For example, here’s the content of the summary file:

$ cat src/SUMMARY.md
# Summary

- [Chapter 1](./chapter_1.md)

And here’s the content of the stub chapter file:

$ cat src/chapter_1.md
# Chapter 1

The ease of generating documentation books with mdbook means that you can quickly and easily document almost anything. Want to see a more complex example? Check out the Void Documenation which is built with mdbook.