GitHub for Static Web Publishing

This tutorial introduces GitHub as a free static website publishing platform. No installation of additional software is required, however, you will need a GitHub account. By the end of this tutorial, you will have your own version of an open textbook template available for further editing. This tutotial is estimated to take between 30 and 60 minutes to complete.

Prerequisities

• A free GitHub account
• Familarity with basic Markdown and YAML syntax

Outline

A faculty member in the social sciences wants to make an open textbook on quantitative methods. The textbook will teach basic data analysis with the R programming language. The faculty member is very knowledgable about R for statistical analysis, but less knowledgable about GitHub and web publishing.

Rather than starting from scratch, we are going to reuse an existing project for our own purposes. GitHub is a platform for sharing and collaborating on projects that are stored as Git repositories. With GitHub, people can share their code projects publicly, license their code, publish packages, report bugs, request features, and troubleshoot software problems. Together, Git and GitHub enable people a free method of sharing and publishing their work online. We’ll be using GitHub features to create, build, and deploy an open textbook using a template that’s available on GitHub.

First, log in to your GitHub account. We will copy and adapt an existing git repository on GitHub in order to make our open textbook. To do this, we will need to “fork” an existing repository. When you create a fork on GitHub, you create a copy of someone elses git repository on your GitHub account in order create your own version of the project.

1. Visit this repository: https://github.com/chrisdaaz/minibookdown
2. Click on the Code tab in the repository view
3. Click on the Use this template button near the top of the page » Create a new repository

The minibookdown repository contains the code we will need to begin creating your own open textbook. You should now have a repository under your account at a web address that looks like this: https://github.com/YOUR_USERNAME/minibookdown

The textbook template comes with a workflow file that generates the output files for the book (i.e. the HTML, PDF, and EPUB versions). We’ll need to enable the workflow file in GitHub:

• Go to the Settings tab
• Click on the Actions sidebar item, select “General”
• Under workflow permissions, select the “Read and write permissions” radio button
• Click on Save

The minibookdown repository we forked to your GitHub account contains the bare minimum of a Bookdown project. Bookdown is a popular open source tool for writing and publishing technical and scientific books from R Markdown files. We don’t need to know anything about the R programming language or statistical computing to use Bookdown for formating and publishing open textbooks. Bookdown will generate PDF, HTML, EPUB, and Word document versions of our open textbook for us.

GitHub, in addition to being a host for source code files, is also a basic file editing system.

1. Edit these lines with the working title and author of your textbook (make sure that the title and authors are in double quotations):

title: "A Mini Bookdown"
author: "Your Name"

2. Once you’re ready to save your changes, scroll down to the Commit changes button. This is also an opportunity to explain the reasoning behing the change. By default, GitHub fills the web form with Update FILENAME but you can change it to something more descriptive, like Adds book metadata.
3. Make sure that the Commit directly to the main branch is selected and click on the Commit changes button

To add chapters, you can create more .Rmd files to your repository:

4. Set the file name. The name needs to begin with two numbers to represent the chapter number, followed by a hyphen (-), the chapter title, and the R Markdown file extention (.Rmd). For example: 01-introduction.Rmd
5. The first line of the file should start with a hash symbol # to represent the title of the chapter. Enter any title following a hash symbol (for example: # Introduction).
6. The contents of the chapter can be written using Markdown syntax.

You can follow in the instructions in the Bookdown manual to continue adding and editing the contents of your open textbook.

By enabling workflow files in our repository, we’ve effectively programmed GitHub to build the HTML, PDF, and EPUB files for our textbook each time we update a file in our project directory. This setting is controlled by the .github/workflows/main.yml file on our repository.

Each time we commit a change to one of the files, the book will re-build. This particular book takes a few minutes for changes to be made because GitHub spins up a new server, downloads our files, installs R, Pandoc, and LaTeX, runs scripts to build the output files, then moves the output files to a new branch called gh-pages. The gh-pages branch serves as a pseudo-server; is where the HTML, epub, and PDF files for our textbook are stored for public online access. This is through the GitHub Pages hosting service for static websites.

Before we can view the web version of our textbook, we have to turn on the GitHub Pages feature.

• Go to the Settings tab
• Click on the Pages sidebar item
• Under the “Build and deployment” settings, change the Source to “Deploy from a Branch”
• Under the “Branch” settings, change to gh-pages branch with the /(root) directory setting
• Click on Save

You now have a publicly available open textbook on GitHub. You can view it by going to https://your-github-username.github.io/minibookdown/.