Chapter 1 From bookdown to GitHub Pages
ReCentering Psych Stats volumes are all created with a combination of R, R Studio, bookdown (the package), the GitHub, GitHub Desktop, GitHub Pages, and a host of packages. There is abundant information on all of these tools across the internet. In this lesson, I walk through the steps in creating the templated bookdown “book” using Yihui Xie’s bookdown package and processes. Two regularly updated sources (Xie, 2021; Xie et al., 2021) provide a strong foundation to this process. Additionally, a quick internet search will yield additional resources for examples, unique circumstances, and idea generation. At the outset, please know that the instructions I provide is based on my experience with my projects and the work that we do in my research team. It is quite possible they will not be as applicable in other contexts.
As I have continued in this journey of learning R, teaching R, and creating an open education resource, I have consulted and relied upon many resources beyond. Visiting the GitHub repository of two resources have been especially useful in gaining these skills. After struggling to comprehend some of the instructions in the bookdown source materials I happened upon a chapter in Dougherty’s, On The Line: How Schooling, Housing, and Civil Rights Shaped Hartford and its Suburbs. I was first drawn to a closing chapter in this open-access digital book that described Dougherty’s (2021) use of bookdwn, the GitHub, and GitHub pages. When I realized that this project was entirely available on a GitHub repo, I learned that I could visit, inspect, and clone (i.e., make a copy of the GitHub repository) of this project. Soon after, I also learned that Navarro’s (Navarro, 2020) Learning Statistics with R was also available in a GitHub repo. Together, the original R Markdown and bookdown training materials plus the two enacted examples were a tremendous resources of potential solutions I could try. For example, on one frustrating day, I could not get my book to build. I cloned Dougherty’s OTL, opened his project on my laptop, and asked the project to build. When it did (flawlessly), I copied and adapted his code (I recall my struggles were in the YAML matter atop the index.rmd) until I could get my project to work. Until very recently, you could still see “otl” references in hashtagged out lines of code in some of the early volumes of ReCentering.
Note. If you are at an institution like mine and you have an enterprise-issued computer it may matter whether your R projects are on your local drive or a cloud-drive. At SPU it is possible to use R Studio with .rmd files and such on the local drive. But they will only knit if the projects are on the OneDrive directory.
1.1 Creating a bookdown template
Before beginning the process, make sure you have installed bookdown:
#install.packages("bookdown", dependencies = T)Additionally, know in advance where (i.e., the parent folder) you want the book to be located. With this in mind:
- Open R Studio
- Under the “File” menu select
- New Project (if prompted, you do not need to save the workspace image, although you may wish to save any files that you have worked on)
- New Directory
- Book project using bookdown
- In the New Project Wizard
- The “Directory name” will be both the project name and the name of the folder that houses all the bookdown parts and pieces. In my example “xtRas” is what I entered in “Directory name.”
- Use the “Browse” button to navigate to the parent folder. In my example, I selected “C/Users/myaccount/OneDrive - InstitutionName/ReCenterPsychStats”
- Create Project
Once created, your project folder will be pre-populated with a number of objects that will serve as tutorials and templates for your work.
1.2 Establishing an Output Directory (needed to publish on GitHub Pages)
If your goal is to present your book through the free webpages of GitHub Pages it is necessary to update some yml matter. Specifically, navigate to the “_bookdown.yml” and edit it by adding script that will route the webpages (and their structure) to a folder titled “docs.” In total, the entirety of script in my “_bookdown.yml” is this:
book_filename: “ReC_extRas” delete_merged_file: true language: ui: chapter_name: “Chapter” output_dir: “docs”
1.3 The index.Rmd File is First
In this section of the tutorial, I navigate to the “index.Rmd” file and merely change the .yml matter related to the title and author so that when we render the book to GitHub Pages we can see that it was, in fact, this project that was rendered.
1.4 Build the Book!
To build the book select the “Build” tab from the upper right hand box in R Studio. Within that tab, select “Build Book.” You can find the rendered book in the docs folder (which it created automatically if you added the command to the *_bookdown.yml* file). Select any of the html files and it will show you the built book.
1.5 Send it to the GitHub
Using the GitHub Pages means that you also have a GitHub account. If you haven’t already, register for an account. Additionally, make sure to download, install and open GitHub Desktop.
Very briefly (because there is so much more), the GitHub is an open source community where you can (freely) create repositories and collaborate on them. The GitHub Desktop allows you to clone your repositories to your local environment, work on them, and then update the GitHub repository. In our case, we are starting with the bookdown R project on our local computer and turning it into a GitHub Repository. From this GitHub repo, it will be pushed to GitHub Pages.
- Open GitHub Desktop
- Under the “File” menu, select
- Add local repository
- With the “Choose” tool, navigate to the the folder that holds the bookdown project (in my case it was “extRas”)
- GitHub Desktop is smart and recognizes that it is not a Git repository. For now it has been working for me to select “create a repository” and use the GitHub Desktop defaults
- Selct “Publish repository”
- Optional to add a description
1.6 Publish on GitHub Pages
Publishing the bookdown project to GitHub pages implies that you have aleady changed the “_bookdown.yml” script to include the output_dir: “docs”
Select “Settings.” Scroll to the bottom, to the “Danger Zone” to make sure that the repository is public. If not, select “Change visibility” and select “Make Public.”
Still in settings, select “Pages” (menu bar on left).
- Under “Source” select:
- Branch: main
- /docs
- save
After a few minutes, your webpage will be available at the website that was provided on the setup for GitHub Pages. It will look like: https:/YOURACCOUNT.github.io/YOURPROJECT/
1.7 Updating via GitHub Desktop
Perpetually in progress texts are continuously updated. When you have updates
- Open GitHub Desktop
- Navigate to the repository
- Use the dropdown menu under Current respository (upper left of app)
- If there are changes in the left panel then an update is appropriate; if there are none, nothing will update.
- Brief text is required in the “Summary” box (lower left)
- It is optional to provide a description. I often leave cryptic summaries and no description. If, however, there was something significant/meaningful, I would elaborate more.
- Click “Commit to main”
- Click “Push origin” found either in the center of the menu bar or in the middle of the page.
That’s it! Depending on the size of the project/changes, all of the documents in the GitHub Repo and the GitHub Pages repo book will be updated. From time-to-time you may wish to cull the GitHub repo to remove older documents that may have been created but replaced (because of renaming or something) and are no longer in use.
1.8 PDF and epub Compilations
It has taken me quite some time to figure out compilation as a PDF. There seem to be a couple of elements that make it successful. First, it is essential to have the tinytex package installed. Use this two-part code:
#install.packages('tinytex')
#tinytex::install_tinytex()Second, inspect the “_output.yml” content.
bookdown::gitbook:
css: style.css
config:
toc:
before: |
<li><a href="./">ReCentering Psych Stats extRas</a></li>
after: |
<li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
edit: https://github.com/USERNAME/REPO/edit/BRANCH/%s
download: ["pdf", "epub"]
bookdown::pdf_book:
includes:
in_header: preamble.tex
latex_engine: xelatex
citation_package: natbib
keep_tex: yes
bookdown::epub_book: defaultAs you can see, the default instructions from the bookdown template include both pdf and epub formats. You can retrieve them from the docs folder.