Bookdown



This book will teach you how to program in R, with hands-on examples. I wrote it for non-programmers to provide a friendly introduction to the R language. You’ll learn how to load data, assemble and disassemble data objects, navigate R’s environment system, write your own functions, and use all of R’s programming tools. Throughout the book, you’ll use your newfound skills to solve. In rstudio/bookdown: Authoring Books and Technical Documents with R Markdown Output Formats. The bookdown package primarily supports three types of output formats: HTML, LaTeX/PDF, and e-books. In this chapter, we introduce the possible options for these formats. Output formats can be specified either in the YAML metadata of the first Rmd file of the book, or in a separate YAML file named. Bookdown 1.x; Introduction: Bookdown 1.x 1. Introduction 1.1. What Is Bookdown? Bookdown: Authoring Books and Technical Documents with R Markdown Output formats and utilities for authoring books and technical documents with R Markdown. 41 Bookdown cheat sheet. 41.1 Heading blah blah; 41.2 About labelling things; 41.3 Cross-references; 41.4 Figures, tables, citations; 41.5 How the square bracket links work; Appendix; A The shell. A.1 What is the shell? A.2 Starting the shell. A.2.1 From within RStudio; A.2.2 Outside of RStudio; A.3 Windows is special and not in a good way.

This extension provides a few amenities for writing with bookdown, such as snippets, highlighting, rendering commands, and auto-completion of cross-references.

Setup

Bookdown

Book Download Pdf

Bookdown

This extension requires R and the bookdown package.

By default, the extension will assume that the R binary is in the system path and can be launched either by R.exe on windows or R on Mac/Linux.If this isn't the case, then the path to the R binary can be specified in the Bookdown.R configuration.

Features

Code Snippets

A list of snippets is in ./snippets/bookdown.json. Typing the prefix will typically cause the snippet suggestion to appear. If not, hit Ctrl + Space to trigger it and Tab to cycle through the different fields.

  • Equations
    • Highlighting and snippets inside the math environment are provided by the LaTeX-Workshop extension
  • Images
    • The preview for the image is provided by the Markdown All in One extension
  • R code chunks
    • Highlighting and snippets inside the codeblock are provided by the R extension

Intellisense autocompletion for cross-references

Cross-references should show up when typing @ref() or through the @ snippet.If it doesn't show up, then try Ctrl + Space to make the suggestion window pop up.

Book rendering

A couple of commands are included for rendering a book.These commands will spawn a new terminal as well, which can be used to monitor the output from R.

Tools for serving the book

  • Bookdown.ServeBook will call bookdown::serve_book('.') in R, and the book should show up in a new browser window. The browser will update whenever the book is edited/saved in vscode.
  • Bookdown.CloseBookServer will close the book server but the R terminal will still keep running.
  • Bookdown.CloseTerminal will close the R terminal.

Tools for rendering the book

The three commands are Bookdown.RenderGitbook, Bookdown.RenderPDFbook, and Bookdown.RenderCustom.The options for these commands are mentioned in the Configuration section below.

Configuration

  • Bookdown.R
    • Type: String, path to R binary, default: '
    • Function: This is needed to launch R and to use the bookdown package. If it is left blank, then the extension will try to use either R.exe or R in the terminal to launch R.
  • Bookdown.ShowTerminal
    • Type: Boolean, default: false
    • Function: If set to true, the terminal will be brought into focus whenever a command is sent to R
  • Bookdown.ShowLog
    • Type: Boolean, default: false
    • Function: If set to true, the extensions log will appear in the output panel for debugging
  • Bookdown.UseRmdFilesYAML
    • Type: Boolean, default: false
    • Function: If false, intellisense will only suggest cross-references that are in the working document. If this config is set to true, then the extension will look in _bookdown.yml for the rmd_files entry and cross-references from all of those files will be shown by intellisense.
  • Bookdown.Opts.Gitbook
    • Type: String, default: 'index.Rmd','bookdown::gitbook'
    • Function: This will be used as the input argument to bookdown::render_book() when rendering a gitbook.
  • Bookdown.Opts.PDFbook
    • Type: String, default: 'index.Rmd','bookdown::pdfbook'
    • Function: This will be used as the input argument to bookdown::render_book() when rendering a pdfbook.
  • Bookdown.Opts.Custom
    • Type: Array
    • Function: This allows any arbitrary output as long as it is supported by bookdown.
    • The default configuration includes settings for an HTML and DOCX document output

Acknowledgements

  • The code for autocompleting cross-references was based on the LaTeX-Workshop extension
  • The syntax injection is adapted from the vscode-fenced-code-block-grammar-injection-example
  • Highlighting of code in R chunks requires the vscode R extension
  • Hightlighting and snippets inside TeX-Math requires the LaTeX-Workshop extension

We built this book with free-to-use, open-source tools, primarily Bookdown, GitHub, and Zotero. This chapter explains why and how we combined these tools and developed our publishing workflow, so that others can build their own books and share their knowledge about how to improve the process.

Why not just write the book in a conventional word processor? We desired an efficient workflow to co-author one manuscript that could continuously generate multiple book products for different purposes, as shown in Figure B.1.

TutorialBookdown
  • HMTL web edition for the open-access book, with embedded iframes for interactive charts and maps
  • PDF print edition with static images and book-style layout
  • Microsoft Word edition with static images for editors who prefer to provide feedback this way
  • Markdown file of the full-length book with pathnames to static images for easy conversion into the publisher’s platform

A conventional word processor could not continuously generate all of these products, which likely would have resulted in creating entirely separate files and code for different editions. But with our unified Bookdown workflow, all of our writing is done in one manuscript. Whenever we make edits, we push a couple of buttons to publish our updated book products in the HTML, PDF, MS Word, and Markdown formats.

Figure B.1: Simplified workflow to compose, compile, and publish in multiple formats with Bookdown. Images from Daniel Hendricks, RStudio, and Zotero.

Here’s a three-minute video that demonstrates the process:

Figure B.2: Short video of our Bookdown workflow. View on YouTube.

Bookdown Overview: Why and How?

Bookdown Example

We based our solution around Bookdown, an open-source package for the R code project created by Yihui Xie at RStudio. Although many people use R for statistical analysis, the free RStudio desktop application also supports several innovative publishing solutions. Here’s an overview of our workflow:

  • We set up the Bookdown files and composed the manuscript in R Markdown, the R-flavored version of the easy-to-write Markdown syntax. Each chapter consisted of one .Rmd file, with links to static images and interactive visualizations.
  • We uploaded our files to a free GitHub repository, which allows multiple authors to work simultaneously on different chapters of the book and “push” revisions (called commits) to a shared online repository, where authors can view each other’s edits. Alternatively, you could simultaneously write and comment on the same chapter in Google Documents, and use the Docs to Markdown add-on to convert one-time into Markdown format, which is similar to R Markdown.
  • We organized our sources using the free Zotero bibliography manager by the Roy Rosenzweig Center for History and New Media at George Mason University. Also, we installed the free Better BibTeX extension by Emiliano Heynes to create Zotero citation keys that work smoothly with Bookdown.
  • After each day’s writing, we used Bookdown to automatically “knit” and compile the book products. Behind the scenes, Bookdown builds the editions using the PanDoc universal document converter and the LaTeX document preparation software, without requiring you to learn these complex formats.
  • Under our open-access agreement with the publisher, we made our book public as we wrote it to develop our audience and address reader feedback. With each day’s revisions, we rebuilt the book and published all of the editions to our public GitHub repository, and used its free GitHub Pages feature to host the open-access HTML web edition. (Alternatively, you can choose to keep your GitHub repo private.)
  • We hosted our open-access web edition on GitHub using a custom domain name (https://HandsOnDataViz.org), which we purchased and set up through Reclaim Hosting.
  • As we worked on the book manuscript, our developmental editor downloaded the PDF edition from our public GitHub repo to mark up with feedback. (Alternatively, some editors prefer to insert track-changes comments in the MS Word edition.)
  • When we were ready to submit the final manuscript, we used Bookdown to create one full-length Markdown file of the entire book, which was compatible with the publisher’s Atlas production platform. However, this was a one-time file conversion, and edits we make to our Bookdown workflow will not appear in the publisher’s platform, unless they request a new file and convert it.
Bookdown

Screenshots of two variations of the basic workflow appear in Figure B.3 and Figure B.4. The first displays how to compose the book using the R Studio built-in editor, and the second shows a very similar process using the Atom text editor, which we prefer. Learn more about GitHub Desktop and Atom text editor in Chapter 10.

Figure B.3: Workflow on a Mac desktop: Compose the text in RStudio and build books with Bookdown (top left), manage sources and insert citation keys with Zotero + BetterBibTex (bottom left), push book products to your GitHub repository to host online (right).

Figure B.4: Variation on the workflow above: Compose the text in your preferred editor (such as Atom), and use RStudio only to build the book products.

Our Bookdown workflow met our goal to efficiently and continuously produce multiple book products. But it may not be ideal for everyone, especially novice computer users. Installation and setup requires several steps, as described in the following sections:

Before leaping into Bookdown or any related tool, see also this section on Alternative Book Publishing Tools.

For more technical details about Bookdown, and examples of other publications built with this tool, see https://bookdown.org:

Bookdown Demo

  • Xie, Yihui. Bookdown: Authoring Books and Technical Documents with R Markdown. Chapman & Hall/CRC, 2018. https://bookdown.org/yihui/bookdown/.
  • Xie, Yihui, J. J. Allaire, and Garrett Grolemund. R Markdown: The Definitive Guide. Chapman & Hall/CRC, 2020. https://bookdown.org/yihui/rmarkdown/.
  • Xie, Yihui, Christophe Dervieux, and Emily Riederer. R Markdown Cookbook. Chapman & Hall/CRC, 2020. https://bookdown.org/yihui/rmarkdown-cookbook/.