Writing books using bookdown package

learn-r

Writing a book is now an amazing experience using R open source software. The R package, bookdown, developed by Yihui Xie, generates printer-ready books and ebooks from R Markdown documents. This package produces books in all output forms (PDF, HTML, ePub, LaTeX, Word and Kindle books etc.). We can also add dynamic graphics and interactive applications (HTML widgets and Shiny apps) to books, and further the package supports a wide range of languages (R, C/C++, Python, Fortran, Julia, Shell scripts, and SQL, etc). Finally, we can publish books in GitHub, bookdown.org, or any other web server of our wish. After referring the ebook wriiten by Yihui Xie, I noted the following basic steps that one has to follow when using bookdown package. For more details, refer the ebook.

  • To learn writing a book with R Markdown and bookdown, download the bookdown-demo from the GitHub repository.

  • Then Install the R package bookdown, and open bookdown-demo.Rproj in the bookdown-demo folder. In this folder, there are several files. For example, index.Rmd,01-intro.Rmd , 02-literature.Rmd, 03-method.Rmd , 04-application.Rmd, 05-summary.Rmd, 06-references etc. The reason for adding 01, 02 etc to the file names, which are the chapters of the book, is that the bookdown merges all Rmd files by the order of filenames. Also, the filenames that start with an underscore _ are skipped. The file index.Rmd, is taken as the first file when merging all Rmd files.

  • However, if we want to override merging Rmd files by the order of filenames, we can use a configuration file named _bookdown.yml in the book directory. In this file, specify the order using the relevant rmd_files. For example, the order may be rmd_files: ["index.Rmd", "Preface.Rmd", "intro.Rmd", "methods.Rmd, ....]
    Suppose we do not want the heading Preface to be numbered. Then we have to add {-} after the heading, as below:

    # Preface {-}

    The files can also be plain Markdown files (.md), which may not contain any R code chunks. In this way, we can use bookdown also to write novels or poems.

  • Now, open the R Markdown file index.Rmd. The YAML meta data of the index.Rmd file of bookdown-demo is given below;

   title: "A Minimal Book Example"
   author: "Yihui Xie"
   date: `"`r Sys.Date()"
   site: bookdown::bookdown_site
   output: bookdown::gitbook
   documentclass: book
   bibliography: [book.bib, packages.bib]
   biblio-style: apalike
   link-citations: yes
   github-repo: rstudio/bookdown-demo
   description: "This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook."

Here the output file is gitbook. But, we can also add bookdown::pdf_book as an output file. See 1.3 usage in ebook. Output formats can be specified either in the YAML metadata of the index.Rmd file of the book, or in a separate YAML file named _output.yml under the root directory of the book. Refer details of the output formats in section 3 of the ebook.

For github-repo, we can use the GitHub repository of the relevant book that we created. In addition to the above meta data, we can also add an image as a cover page. e.g. cover-image: "images/cover.png".

  • Each chapter of the book has one R Markdown file, and these .Rmd files should start with the chapter title using the first-level heading, e.g., # Introduction {#intro} without the YAML meta data. Here, {#intro} is a label for the chapter and later we can reference this chapter as \@ref(intro).

  • We can add Figures and tables with captions in figure and table environments, respectively. For example, suppose the first figure is added to the chapter as below:

{r fig1, fig.cap='This is figure 1', out.width='80%', fig.asp=.75, fig.align='center'}
   par(mar = c(4, 4, .1, .1))
   plot(data, type = 'b', pch = 19)

Then, later if we want to refer this figure we can use it’s label fig1, e.g., see Figure \@ref(fig:fig1). If we want to include images that are not generated from R code, then we can use the function knitr::include_graphics(). For example, to include 3 images side by side set out.width = '33%' .

  • Suppose we added a table using knitr::kable() to the document as below:
{r tab1, tidy=FALSE}
   knitr::kable(
     head(dataset, 20), caption = 'This is Table 1',
     booktabs = TRUE

As we used the label to refer fig1, we can now refer this table later as \@ref(tab:tab1), where tab1 is the label of this table .

  • Refer section 2.2.1 for understanding how to number the equations in the book. Also, for adding theorems, lemmas, proofs etc refer section 2.2.2 of the ebook. For example, a theorem having a name and a label can be written as
{theorem, name="Newton's theorem", label="thm1"}
   Write the theorem here

The label is important since that can be used to refer the theorem later. e.g. \@ref(thm:thm1). When adding proof, remark, and solutions we can do the same methods that we apply for theorem environment. We can name them, but we cannot refer them since they are unnumbered. Further, we have to set chunk option echo=TRUE in theorem and proof environments, otherwise they will be hidden.

  • To add citations, we can use BibTeX database, which is a plain-text file with an extension .bib. An example bib text file for an article is shown below:
@article{tm,  
     title = {Text Mining Infrastructure in R},  
     author = {Ingo Feinerer, Kurt Hornik, and David Meyer},  
     year = {2008},  
     journal = {Journal of Statistical Software},  
     volume = {25},  
     number = {5},  
     pages = {1-54},  
     url = {http://www.jstatsoft.org/v25/i05/},  
     }

Here tm is the citation key which can be used to cite this article in the text. For example, if we use @tm it rendered as Ingo Feinerer, Kurt Hornik, and David Meyer (2008), and [@tm] generates (Ingo Feinerer, Kurt Hornik, and David Meyer (2008)).

Suppose we have created two .bib files, book.bib, and packages.bib . Then add the following lines to the YAML metadata of the index.Rmd file. Refer the YAML metadata stated in the 4th step of this document.

bibliography: [book.bib, packages.bib]  
   biblio-style: apalike  
   link-citations: true

  • We can also include HTML widgets, web pages and Shiny apps to the content of the book. See sections 2.10 and 2.11 of the ebook.

  • If we use HTML as the output form, we can use the GitBook style, or the Bootstrap style, or the Tufte style. In the GitBook style, there is a sidebar having the table of contents on the left, and the main body of a book on the right. This design is responsive to the window size. More details refer this section,

    The Bootstrap style, is the default style of the HTML output of R Markdown. More details refer section 3.1.2 of the ebook.

    In the Tufte style, the main body of the book is on the left and a margin column which uses to place footnotes, margin notes, references, and margin figures, etc is on the right. For more details refer section 3.1.3 of the ebook.

  • Yihui Xie strongly recommends to use the HTML output format instead of LaTeX when developing a book. When finish writing LaTeX/PDF output format can be considered. Refer section 3.2 of ebook and pandoc manual for setting up YAML meta data for this format.

  • Two e-book output formats, EPUB and MOBI. are available for bookdown. To create EPUB book use documentclass: epub_book(). For more details refer section 3.3.1 of the ebook. For Amazon’s Kindle devices we have to create MOBI e-books. Refer section 3.3.2 of ebook for more details.

  • Details for customizing your book read Chapter 4 of the ebook.

  • To built the book call the render_book() function. There are two approaches to render a book; “Merge and Knit” (M-K) and “Knit and Merge” (K-M), respectively. If we use M-K approach, we cannot have duplicate labels in the book chapters. For the K-M approach, we should not include duplicate labels within any single Rmd file. Also, if we use K-M approch we can include Rmd files in subdirectories, but when using M-K it is not allowed. The default approach in bookdown is M-K. To switch to K-M, we have to use the argument new_session = TRUE when calling render_book(), or set new_session: yes in the configuration file _bookdown.yml.

  • In render_book() function one option is “output format”. This option will be the first output format specified in the YAML metadata of the first .Rmd file or a separate YAML file _output.yml. To bulid the book we can either click the button Build Book on the Build tab of RStudio, or run the code.

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

    After adding or changing any R Markdown file, we can preview the book by clicking the Knit button.

  • To publish the book we can consider one of the following options: (i) Host the HTML files on a web server. (ii) Upload the book to https://bookdown.org (iii) Host the book on GitHub via GitHub Pages (https://pages.github.com). For more details refer section 6. For self publishing refer “How to self-publish a book” and “How to self-publish a book: customizing bookdown”.

  • Don’t forget to go through R Markdown Tutorial for bookdown, blogdown, and xaringan by Yihui Xie

Happy bookdown!!!