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.
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.
Inside RStudio, select the Packages tab, and select Install. See screenshot
Inside RStudio, install the “bookdown” package to build your book, and select Install Dependencies. See screenshot
Bookdown now should be successfully installed in RStudio. See screenshot
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
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
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.1or higher. To install a newer version of Pandoc, which is highly recommended, go to https://pandoc.org.
In RStudio > Packages tab > System Library screen, be sure to check boxes for
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
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.
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.
In your web browser, log into your GitHub account, go to the Bookdown developer’s
bookdown-minimalrepo https://github.com/yihui/bookdown-minimal, and fork a copy to your GitHub account.
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.
In your web browser, go to your forked copy of
bookdown-minimal, click the green
Codebutton, 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.
In RStudio in the upper-right corner, select Project > Open Project to open the
bookdown-minimalfolder on your local computer. See screenshot
In RStudio, open the
index.Rmdfile 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
Optional: If you wish, you can modify your
bookdown-minimalfiles outside of RStudio, by using your preferred text editor, such as Atom editor https://atom.io.
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.
If RStudio successfully builds both editions of your minimal book, the output will be saved into your
bookdown-minimalfolder, 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.htmlfile with our regular browser.)
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
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.
Open GitHub Desktop and navigate to the
bookdown-minimalfolder 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.
In your web browser, go to your online GitHub repo, with a web address similar to
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.
Scroll down to the GitHub Pages section again, and the web address of your published site should appear similar to
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
index.htmlserving as the home page. Therefore, the full web address in your new browser tab should be similar to:
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.
On The Line © 2022 by Jack Dougherty and contributors is freely shared under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license.