Tutorial-style docs with mdBook

Introduction

API documentation tools are useful when documenting code. But if the document that you are writing is mainly structured prose with a small-ish amount of code in it, like the text that you are currently reading or user tutorials in general, there are nicer alternatives.

Static Site Generators (SSGs) that generate HTML from Markdown have gained tremendous popularity for this application in recent years because…

Starting from a plain text format makes it much easier to use version control systems.
Targeting HTML lets you leverage the huge ecosystem of web tools and hosting providers.
Among the various plain text formats that compile to HTML, Markdown is by far the most popular option, and arguably one of the easiest to learn.

Unfortunately, Markdown by itself (including its CommonMark standardized dialect) does not specify enough functionality to ease the writing of complex, multi-page documents. Hence we often need to tie ourself to a specific renderer that extends Markdown enough to make it useful. In this practical, we will use mdBook for this purpose.

Getting started with mdBook

There are many alternatives to install mdBook on a machine. For the sake of simplicity, mdBook is already installed on the virtual machines that you are using.

Initialisation of the book

The mdbook init command will create a new directory containing an empty book for you to get started. Give it the name of the directory that you want to create:

mdbook init my-first-book

It will ask a few questions before generating the book. After answering the questions, you can change the current directory into the new book, and inspect the directory:

$ tree -L 2 .
.
├── book
├── book.toml
└── src
    ├── chapter_1.md
    └── SUMMARY.md

2 directories, 3 files

The file book.tomlcontains settings for describing how to build your book. This is written in the TOML markup language. The default settings are usually good enough to get you started. When you are interested in exploring more features and options that mdBook provides, check out the Configuration chapter for more details.

The folder src contains your source code to build the book, written in markdown. You can add as many files as you want. Note that the SUMMARY.md file contains the definition of the table of content. You can have many files in src, but only those defined in SUMMARY.md will actually appear on the rendered book.

Finally the folder book, initially empty, will contain the rendered book.

Rendering a book

There are several ways to render a book, but one of the easiest methods is to use the serve command, which will build your book and start a local webserver. As you are on a Virtual machine, you have to specify the hostname, as well as a port that is open:

mdbook serve --hostname <IP> --port <PORT>

where <IP> is the IP of your machine, and <PORT> is set to 24000 here (we opened this port for you). Just follow the displayed URL on the terminal to read your book. You can leave the server running even while you edit the content of the book, and mdBook will automatically rebuild the output and automatically refresh your web browser. Note that now the book folder contains many more files (recreated each time you make modifications in the src folder).

Publishing a book

Once you have written your book, you may want to host it somewhere for others to view. The first step is to build the output of the book. This can be done with the mdbook build command in the same directory where the book.toml file is located:

mdbook build

This will update the directory named book which contains the HTML content of your book. You can then place this directory on any web server to host it.

For more information about publishing and deploying, check out the Continuous Integration section from the mdBook documentation, and we will play with a concrete example at the end of this training (Continuous integration).

Exercise: build a logbook

Build a new book, whose sections follow the sections of this training. In each section, you will write your findings, notes and feedback about this training :-)

Robust Programming