Install and Set Up Bookdown

Below are steps we followed to set up the Bookdown publishing platform and related tools for this book, using our Macintosh OS 10.14 computers. The same general principles also should apply to Windows computers. No special knowledge is required, but these tools may not be ideal for novice computer users. Installation steps—and inevitable problems that pop up—will be easier if you are comfortable with exploring your computer, or already have some familiarity with text editors, GitHub, or R Studio.

  1. Install R Project statistical programming language https://www.r-project.org, which is required by Bookdown. See screenshot

  2. Install the free version of RStudio Desktop to make R easier to use with a visual editor. See screenshot. Some authors compose their books in RStudio, but you may use any text editor. Our personal preference is the Atom editor from GitHub.

  3. Inside RStudio, select the Packages tab, and select Install. See screenshot

  4. Inside RStudio, install the “bookdown” package to build your book, and select Install Dependencies. See screenshot

  5. Bookdown now should be successfully installed in RStudio. See screenshot

  6. For Bookdown to create a PDF edition of your book, you need to install a LaTeX engine to prepare your Markdown plain text, citations, and images into stylized pages. Since the full-sized LaTeX project is very large, Bookdown recommends the smaller TinyTeX package. Inside RStudio, select the Packages tab, select Install, and enter “tinytex” to find and upload the package. See screenshot

  7. To finish installing tinytex, in the RStudio console, type tinytex::install_tinytex() and press return. See screenshot

Note: If a permissions error displays that /usr/local/bin not writable see solution at https://github.com/yihui/tinytex/issues/24

  1. When you installed RStudio, it also should have installed its own version of Pandoc, the package that converts files from Markdown format to HMTL and other formats. To confirm the Pandoc installation and version number, in the RStudio console, type rmarkdown::pandoc_version() and press return. The resulting version number should be 2.3.1 or higher. To install a newer version of Pandoc, which is highly recommended, go to https://pandoc.org.

  2. In RStudio > Packages tab > System Library screen, be sure to check boxes for bookdown and tinytex packages.

  3. To display your platform and package settings in RStudio, type xfun::session_info() and it will display results similar to this:

R version 4.1.0 (2021-05-18)
Platform: aarch64-apple-darwin20 (64-bit)
Running under: macOS Big Sur 11.3.1

Locale: en_US.UTF-8 / en_US.UTF-8 / en_US.UTF-8 / C / en_US.UTF-8 / en_US.UTF-8

Package version:
  base64enc_0.1.3   bookdown_0.22     compiler_4.1.0    digest_0.6.27    
  evaluate_0.14     glue_1.4.2        graphics_4.1.0    grDevices_4.1.0  
  highr_0.9         htmltools_0.5.1.1 jsonlite_1.7.2    knitr_1.33       
  magrittr_2.0.1    markdown_1.1      methods_4.1.0     mime_0.11        
  rlang_0.4.11      rmarkdown_2.9     stats_4.1.0       stringi_1.7.3    
  stringr_1.4.0     tinytex_0.32      tools_4.1.0       utils_4.1.0      
  xfun_0.24         yaml_2.2.1

Download, Build, and Host a Sample Bookdown Book

While Bookdown does not require you to use GitHub, these steps show how to integrate these tools to make your own copy of a sample Bookdown book.

  1. Create a free GitHub account to simplify steps for the next two sections. While Bookdown does not require you to use GitHub, the workflow described below features GitHub to copy a sample Bookdown template and to host your own Bookdown editions online. To learn more about the basics of this tool, see Chapter 11: Edit and Host Code with GitHub.

  2. In your web browser, log into your GitHub account, go to the Bookdown developer’s bookdown-minimal repo https://github.com/yihui/bookdown-minimal, and fork a copy to your GitHub account.

  3. Install GitHub Desktop https://desktop.github.com to transfer files between your online GitHub repo and local computer. While software developers may prefer to access GitHub by typing commands in their terminal, GitHub Desktop provides easier point-and-click access for most users.

  4. In your web browser, go to your forked copy of bookdown-minimal, click the green Code button, and select Open in Desktop. This should automatically open the GitHub Desktop application, and you can navigate where you wish to store a copy of your code repo on a folder in your local computer.

  5. In RStudio in the upper-right corner, select Project > Open Project to open the bookdown-minimal folder on your local computer. See screenshot

  6. In RStudio, open the index.Rmd file and make some simple edits to the text of this minimal book. For example, remove the hashtag # comment symbol in line 8 to “uncomment” and activate the PDF book option. Save your edits. See screenshot

  7. Optional: If you wish, you can modify your bookdown-minimal files outside of RStudio, by using your preferred text editor, such as Atom editor https://atom.io.

  8. In RStudio, upper-right corner, select the Build tab, select Build Book, and choose All Formats to build both the gitbook-style static web edition and PDF edition.

  9. If RStudio successfully builds both editions of your minimal book, the output will be saved into your bookdown-minimal folder, in a subfolder named _book, because that’s how this sample is configured. The RStudio internal browser should automatically open your web edition (but it’s not a very good browser, so we typically close it and manually open the index.html file with our regular browser.)

  10. Also, open the subfolder and inspect the PDF edition of your book. If any errors were generated in the process, error messages will appear in red type in the RStudio Build viewer, which may require you to debug errors and delete temporary files as instructed. See screenshot.

Tip: In future sessions with RStudio, you should select the Packages tab and click Update to keep Bookdown and other software packages up to date. See screenshot

  1. Close your project, and quit RStudio. The next set of steps will focus on pushing your edited book to your GitHub repository using the GitHub Desktop tool.

  2. Open GitHub Desktop and navigate to the bookdown-minimal folder on your local computer. Write a quick summary to commit (or save) the changes you made above to your main branch, and push this version to your online GitHub repo.

  3. In your web browser, go to your online GitHub repo, with a web address similar to https://github.com/USERNAME/bookdown-minimal.

  4. In your GitHub repo, select Settings, and scroll down to the GitHub Pages section, which is a free web hosting service to publish your code and book editions on the public web. Change the Source from None to Main, keep the default /root option in the middle, and press Save.

  5. Scroll down to the GitHub Pages section again, and the web address of your published site should appear similar to https://USERNAME.github.io/bookdown-minimal.

  6. Copy your published web address from above, paste into a new browser tab, and at the end add _book/index.html. The reason is because your sample book is configured by default to store all web and PDF editions in your _book subfolder, with index.html serving as the home page. Therefore, the full web address in your new browser tab should be similar to: https://USERNAME.github.io/bookdown-minimal/_book/index.html

Tip: You may need to wait up to one minute for edits to your GitHub online repo to appear live at your GitHub Pages web address. Also, after waiting for GitHub Pages to make changes, be sure to “force reload” or “hard refresh” your web browser to update directly from the GitHub Pages server, not the browser’s internal cache.

footer