\( \newcommand{\symbf}[1]{\boldsymbol{#1}} \)

Lecture 1 Introduction

Bookdown is a free package for creating lengthy documents, like books and complete lecture notes, in HTML, PDF, and EPUB (e-books) formats. Given the legal requirements for producing accessible and inclusive online documentation, that are coming in force very soon, we are particularly interested in the HTML format, and Bookdown allows to produce very neat web documents without any knowledge of the html language. For mathematicians, the most valuable feature of Bookdown is its use of LaTeX syntax to generate mathematical expressions. Since we are all quite proficient in writing LaTeX documents, this is very good news indeed.

However, Bookdown was developed by the \(\mathbf{R}\) community for the \(\mathbf{R}\) community. In fact, this is an extension of the so-called R-markdown package that was developed with the purpose of creating an integrated environment both for statistical computations and producing reports on their outcome at the same time. As a result, an R-markdown file includes not only normal text and instructions of how to structure it, incorporate figures, tables, etc., but also “chunks” of R-code for computations that produce the data for these figures and tables. While this must be a great tool to those who work in Statistics, to the rest of us, who just want to produce inclusive and accessible documents on the web, these features are unnecessary and confusing complications. However, there does not seem to be anything better for this purpose on the software market at the moment1 .

Due to its rooting in R, Bookdown is not particularly friendly to those who are not part of the R community. This is reflected in the package documentation, which in places looks bewildering to an outsider. However, things are not as bad as they look, and after a proper introduction one can produce nice web documents in a reasonably short time. The purpose of this guide is to fill the gap in the existing documentation. Moreover, we aim at step-by-step instructions of how to use Bookdown for producing html lecture notes and uploading them on the Blackboard page of your module.

It is important to understand that while Bookdown can produce output in all 3 formats simultaneously, it uses different engines for different formats, e.g. Mathjax for HTML and LaTeX for PDF. As a result, what works fine for one format may not work for another and some additional fiddling may be required. This may involve the so-called conditional compilation, where you use conditional constructions of R in order to execute different sets of instructions depending on the output format. For our purpose, the most important output format is HTML (the gitbook building option in particular). Fortunately, this is where Bookdown does its best and yields very neat web-pages. The corresponding PDF documents are also quite good and will be available for download via the web-page. However, normal LaTeX is a more flexible and powerful tool for producing customised PDF documents. The e-book output (in EPUB format) seems a bit problematic. It may be possible to get a good result in the end, but with extra effort and some compromises. Accompanying this guide is a template distribution, prepared by the author. This is a complete Bookdown project distribution, with R-markdown files, configuration files, etc. Follow the link to download it: bookdown-template.zip

The author worked on MacBook Air laptop running macOS Catalina (Version 10.15.5). Things may look somewhat different on other platforms. This guide summarises what the author has learnt from various manuals, personal experimentation, and internet forums. It is far from being comprehensive. As our expertise improves, the guide will be updated and any suggestions on the matter are welcome. When you hit a problem not addressed in the guide, you may find useful consulting with other existing manuals. These and other support can be found at


  1. Though, see LaTeXML for a “quick-fix” approach.↩︎