13 GitHub Pages

In this lecture, you will learn how to create a website in GitHub if you ever feel the need to show off.

As you advance in your career as an academic, you may want to create a professional web presence. Of course, you are welcome to create a website using Wordpress, which is probably the easiest and least time-consuming way to have a web presence. But I see more GitHub Pages from political scientists popping up everyday and I fear that it may become some sort of signal in the discipline, like LaTeX and Beamer before it.

So, here you will learn how to host a website on GitHub Pages.

13.1 What’s so great about GitHub Pages?

  • Create content the same way you create R Markdown documents (you don’t have to learn anything new…kinda)
  • Track your changes
  • Create project pages
  • You can signal that you know how to use GitHub Pages!

13.2 Who uses GitHub Pages?

Tons of famous & important people (mostly quantitative methodologists) in the discipline, including…

13.3 Steps to get your GitHub Pages up & running

Here is how you become one of the elites. The best tutorials I’ve found thus far are:

13.3.1 Prerequisites

  1. You should have Git 2.8 installed on your machine.
  2. You should have a Github account.

13.3.2 Step 1: Install Hugo

Serious academics seem to prefer Hugo because they can then use the Academic theme.

13.3.3 Mac Users

You should definitely install homebrew. It’s a quick and easy tool that helps you install packages that do not exist on your Mac.

After you install homebrew, you can install Hugo via the Terminal:

brew install hugo

You might want to verify that you have the latest version of hugo:

hugo version

13.3.3.1 Windows users

You should definitely install Chocolatey. It’s a quick and easy tool that helps you install packages that do not exist on your PC.

After you install Chocolatey, you can install Hugo via the Command Line:

choco install hugo -confirm

You might want to verify that you have the latest version of hugo:

hugo version

13.3.4 Step 2: Create site

You want to create a new Hugo site on your computer.

hugo new site hugo_site

13.3.5 Step 3: Add theme

You want to pull a Hugo theme from the web and load it to the Hugo site on your computer.

For the purpose of this demo, we will use the Ananke theme. You are free to pick whatever Hugo theme you want to use. Prior to this lesson, you have hopefully chosen the theme you would like to use.

Enter the following into the terminal:

cd hugo_site
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Then you want to make sure the config file points to the ananke theme, so you enter some additional commands into the terminal:

echo 'theme = "ananke"' >> config.toml

One thing I’ve noticed about changing themes for your Hugo website is that it can be pretty annoying. In essence, you need to copy the theme files whenever you download a new theme and change the config file to make sure it points to the new theme. But you might run into some issues with your existing site and need to revise a few files, etc. Anyway, we can obsess over this problem once it becomes a problem.

13.3.6 Step 4: Add content

You want to add a page to your website. Enter the following command into the terminal:

hugo new posts/my-first-post.md

Here, you are telling Hugo to create a new post titled my-first-post.md to your Hugo site.

Find the my-first-post.md file in your posts folder and add the following header to the file:

---
title: "My First Post"
date: 2019-03-26T08:47:11+01:00
draft: true
---

As long as you put draft: true, the page will remained unpublished…until you set it to false, making it no longer a draft and giving Hugo permission to publish it.

13.4 Step 5: Fire up the Hugo server

You want to start hosting your site on your computer. So you need to enter the following command into your terminal:

hugo server -D

Now you will be able to preview your site at http://localhost:1313/. You can continue making edits to existing posts and adding new posts, and you will be able to see the edits after you refresh your preview site.

To stop previewing the site, go to the terminal and enter CTRL+C. If you do this, the site will still be in the browser, but you will no longer be able to refresh and preview updates to the site.

13.4.1 Step 6: Configure your site

You have your site hosted on your computer, but what’s the point if no one else can see it but you? You need to start thinking about hosting your site on the web. Find your config.toml or config.yml file and edit the following:

baseURL = "https://[your-username].github.io"
languageCode = "en-us"
title = "[Your name]"
theme = "[Your theme]"

Save the file.

13.4.2 Step 7: Build pages

This might be a weird thing to have to wrap your head around, but there are two components of a GitHub Pages website:

  • the one you edit
  • the one people see

You edit the .md files, but you want people to see the .html files. In order for people to see the public-facing files, you need to build them. To do so, you enter the following command into the terminal:

hugo -D

Then you will see a public folder of some sort in your folder.

13.4.3 Step 8: Create repositories on GitHub

Create the following two repositories on your GitHub:

  1. website: contains the files you edit
  2. [your-username].github.io: contains the public-facing site

13.4.4 Step 9: Pull git repository on to your computer

You want to pull the git repository that you will fill with the files you want to edit on to your computer.

git clone https://github.com/[your-username]/website.git > && cd website

Then you want to copy all the files from your hugo_site folder and paste it into the website folder.

You want to make surer everything works, so you need to type the following command into the terminal:

hugo server

Again, you can go to http://localhost:1313 to preview your site and use CTRL+C to exit the preview.

13.4.5 Step 10: Change public-facing location

To change where you want to host your public-facingn files, you need to remove the public folder in your website repository. You can do this by using the following command:

rm -rf public

13.4.6 Step 11: Create public-facing location

You will need to create a submodule, which allows you to include or embed repositories as a subfolder within another repository. To do this, you need to run the following command in the terminal:

git submodule add -b master https://github.com/[your-username]/[your-username].github.io.git public

In essence, the public site has now been “projected” on to your [your-username].github.io website.

13.4.7 Step 12: Execute changes

You want to create a file named deploy.sh and put it in your website folder. Inside the deploy.sh file, insert the following.

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Build the project.
hugo

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

In the terminal, type in the following command, which makes it executable. In other words, it gives your computer permission to run the code inside the .sh file.

chmod +x deploy.sh

Then you run the following code to deploy your changes in the website folder onto your [your-username].github.io website:

./deploy.sh "insert your commit message here"

13.4.8 Step 13: Check out your site

After your first commit, it may take up to 10 minutes for your new website to show up on [your-username].github.io. I’ve noticed that it takes a few minutes for changes to show up even after the first commit, so something to keep in mind.