Skip to content

03 Building books with bookdown

Jump to bottom
Neha Moopen edited this page Aug 5, 2021 · 12 revisions

While individual chapters are written as R Markdown (.Rmd) files, these are rendered to HTML and compiled into a 'book' using the bookdown package in R.

The bookdown package is built on top of R Markdown, and inherits the simplicity of the Markdown syntax, as well as the possibility of multiple types of output formats (HTML, PDF, Word). It has also added features like multi-page HTML output, numbering and cross-referencing figures/tables/sections/equations, inserting parts/appendices to create elegant and appealing HTML book pages.

The Handbook is an example of how you can produce a 'book' from a series of R Markdown documents meant to be read in a linear sequence.

Usage

Thanks to our CI/CD workflow (outlined in the next Wiki page), you don't necessarily have to build the book locally on RStudio. You can do it for your own convenience of course, for example, if you want to preview your edits as you go.

The following section outlines the initial setup, so current and future maintainers know how the book was tailored to our needs.

Installation

You can install the package from CRAN as follows:

install.packages("bookdown")

Initial Setup

  1. First of all, the package was loaded using the following command:

library(bookdown)

  1. For the Handbook, the first step was to create a skeleton project using the following command:

bookdown:::bookdown_skeleton(getwd())

  1. The above command does not generate a R Project (.Rproj) file. This was created manually by going to File -> New Project... -> Existing Directory -> dataprivacyhandbook.Rproj

  2. R Markdown (.Rmd) files were added per chapter.

  3. Specifications in the _bookdown.yml page were edited as follows:

  • book_filename: was specified as "dataprivacyhandbook"
  • output_dir: was added and set to "docs" (instead of the default "_book" directory)
  • chapter_name: was set to ""
  1. Specifications in the _output.yml page were edited as follows:
  • number_sections: was added and set to false
  • split_by: was added and set to section
  • collapse: was added under toc and set to section
  • before: was set to <li><a href="./">Data Privacy Handbook</a></li>
  • after: was set to <li><a href="https://github.com/UtrechtUniversity/dataprivacyhandbook" target="blank">Visit the GitHub repository</a></li>
  1. The book was then rendered using the following command:

bookdown::render_book("index.Rmd", "bookdown::gitbook")

References

  1. bookdown: Authoring Books and Technical Documents with R Markdown
  2. https://github.com/rstudio/bookdown
  3. https://bookdown.org/
Clone this wiki locally