Mdbook

Mdbook is an amazing tool, it allows to write something piece by piece and assemble them in a book. It is extremely easy to use, you write in markdown the content of each chapter, then write the summary and let mdbook do the rest. It will then produce an html website according to the content. You can also produce a real book or an ebook using some plugins.

Let me show you in detail how it work. First let’s initialise the book :

mathieu@Balder ~/book ❯ mdbook init mynewbook

What title would you like to give the book?
My New Book Example
2024-06-13 09:21:20 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

mathieu@Balder ~/book ❯ ls
mynewbook

mathieu@Balder ~/book ❯ cd mynewbook/

mathieu@Balder ~/book/mynewbook ❯ ls
book  book.toml  src

Mdbook has created a directory for the book content, in that directory there are two folders and one file. The file book.toml describes the book metadata and the info required to build the book. By default it will build an html website and use the “src” directory.

mathieu@Balder ~/book/mynewbook/src ❯ ls
chapter_1.md  SUMMARY.md

In the “src” directory there are two files, the summary and the first chapter. The summary is the backbone of the book it will describe the book content.

mathieu@Balder ~/book/mynewbook/src ❯ cat SUMMARY.md
# Summary

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

By default there is just one chapter. I’ll add one by simply adding a line in the summary file.

mathieu@Balder ~/book/mynewbook/src ❯ echo "- [Chapter 2](./chapter_2.md)" >> SUMMARY.md

I can then build my first book.

mathieu@Balder ~/book/mynewbook ❯ mdbook build
2024-06-13 09:32:38 [INFO] (mdbook::book): Book building has started
2024-06-13 09:32:38 [INFO] (mdbook::book): Running the html backend

Mdbook informs me that it builds the book (an html site) using the html backend. Now I’ve got a perfectly fonctionnal website in the book directory.

mathieu@Balder ~/book/mynewbook/book ❯ ls
404.html           chapter_2.html      favicon.png  highlight.css  print.html        tomorrow-night.css
ayu-highlight.css  clipboard.min.js    favicon.svg  highlight.js   searcher.js
book.js            css                 FontAwesome  index.html     searchindex.js
chapter_1.html     elasticlunr.min.js  fonts        mark.min.js    searchindex.json

mathieu@Balder ~/book/mynewbook/book ❯ firefox index.html

Mdbook can also generate dynamically the content of this directory and open my webbrowser

mdbook serve --open

It can also render it as a pdf book using extensions, i’ve used mdbook-pdf for this example). All i need to do is install mdbook-pdf and add to my book.toml file the required parameters.

mathieu@Balder ~/book/mynewbook ❯ cat book.toml

[book]
authors = []
language = "en"
multilingual = false
src = "src"

[output.html]

[output.pdf]

mathieu@Balder ~/book/mynewbook ❯ mdbook build
2024-06-13 11:12:27 [INFO] (mdbook::book): Book building has started
2024-06-13 11:12:27 [INFO] (mdbook::book): Running the html backend
2024-06-13 11:12:27 [INFO] (mdbook::book): Running the pdf backend
2024-06-13 11:12:27 [INFO] (mdbook::renderer): Invoking the "pdf" renderer
Generating PDF, please be patient...
PDF successfully generated at: /home/mathieu/book/mynewbook/book/pdf/output.pdf

My book is now also available in pdf format in the repository book/pdf/output.pdf