Building a website using Github pages and Hugo

9-minute read
Tutorial • Website
Hugo • Atom • Shell

If your situation is at all similar to mine right now, the COVID pandemic has greatly impacted day-to-day research operations and probably has had an impact on your productivity. Many of the tasks I queued up are now pushed way back, and there is a void of time that needs filling - preferably with something other than Netflix and binge-snacking…

So, why not build a website for yourself (or a project you are working on)!

I recently moved my personal website from Wordpress to Github pages running a Hugo site. If none of that makes any sense to you, no worries! Two months ago I had no experience with either Github pages or Hugo.

However, this tutorial does assume a few things:

  1. You have some experience with using .git version control
  2. You’ve used the terminal to use either .git or do basic Shell scripting
  3. You have a Github account and have used Github to host .git project repositories
  4. You’re familiar with, or have heard of Markdown
  5. You have a rough idea of what you’d like your site to do/look like (i.e., you want a virtual CV, or blogging capabilities)

What is Hugo?

Hugo is a nifty framework for quickly developing simple websites, like an online portfolio or CV. To borrow parlance from a language that may be more familiar, it’s kind of like an installing a package in R package that contains the functions and tools to easily build a website. You don’t need to know a ton about css or html and can get a site up and running in just a couple of hours. There are a bunch of free themes that will help you build out your site and very helpful documentation to help troubleshoot issues. What’s more, you’re able to build pretty much the entire site by writing in Markdown rather than html. This was the key for me as a recent Markdown convert.

What are Github pages?

One of the most confusing things about building a website for me has always been figuring out hosting - or who stores the files for your site. Wordpress provided an easy way to pay a nominal fee to get someone else to worry about it for me. However, using Wordpress forces you to lose some customizability and I don’t think you learn as much that way. Github pages is a nice way to learn a bit more about the “under the hood” operations that make a website work, while doing all of the annoying backend stuff of hosting the site, etc. You just need to build the site content and Github pages pretty much does the rest!

What we’re going to do:

  • Use the terminal to install Hugo
  • Initiate a website directory (folder) and monitor it with git
  • Use terminal/Hugo to build a simple website
  • Add some basic content: a new page, a blog post
  • Build and test the site locally (using your computer as the web server)
  • Commit/push the changes you’ve made to a Github repository
  • Some fancy scripting magic to build the site on Github pages

Let’s dig in…

1. Install Hugo

The first thing we need to do is to install Hugo onto your computer.

Start by opening your terminal and type the following to install Hugo (you may need to first install Homebrew:

brew install hugo

Tada! Easy, no?

2. Create a new Hugo site

Before we do this, let’s change our working directory to wherever you want your website files to live on your computer. Mine are in a folder within my documents. For example, in terminal, enter:

mkdir "./Documents/my_new_website"

to create a new directory called my_new_website. You can then make this your working directory by entering:

cd ./Documents/my_new_website/

Cool! Your site will be created within this folder. We can then use the basic template built into Hugo to create a new site.

hugo new site quickstart
# Change `quickstart` to whatever you'd like to call your site

That will create a new site! You’ll see that, within your my_new_website directory, a new folder was created called quickstart. Inside that folder is the directory structure for the new site!

test_site_dir

Add a website theme

Now, let’s add a theme to make the site look pretty. If you’d like to specify a different theme than the default (called “Ananke”), take a look at some pre-built themes and download one. You’ll then need to drop that folder into the themes folder within your site directory.

In this step, we’re changing our working directory to the new quickstart folder and also creating a git repository to track all of the changes that we make to files in our project.

cd quickstart
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke # Ignore this command if you downloaded your own theme `.git` file and placed it in your themes folder within `./quickstart/themes`

Now we need to tell our website that we have a new theme that we want it to use. The code below will make an adjustment to a parameter within the config.toml file that already exists in our project directory (be sure to change name of theme if you’re not using ananke).

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

Sweet! We have the start of a website. Now it’s time to create some basic content. We’ll make a blog post and a new webpage.

Make new blog post/webpage

Creating content for Hugo requires you to write in Markdown. Don’t worry - it’s incredibly simple and will probably revolutionize how you write stuff, generally! I use Markdown now for pretty much everything now - I love it! :)

Creating content is easy. The code below will create a new blog post in your content folder, within a subfolder called posts.

hugo new posts/my-first-post.md

You can then open this file in any text editor (my personal favorite is Atom) and start writing away! Check out this guide for writing in Markdown.

Each post/page you make will begin with some canned content called the “header”. This provides some parameters to control your posts/pages. It will look something like this:

---
title: "Photography"
date: 2020-02-19T09:49:04-08:00
draft: false
---

Creating a new webpage is just as simple.

hugo new my-new-page.md

Preview your website

So far, we’ve only been working in Terminal and the file explorer. But what does our site actually look like??? Let’s boot up a copy of it using our computer as the server and find out!

hugo server -D
# The -D here tells the command to include all draft posts/pages

A bunch of stuff will pop up in your terminal, but the important bit at the bottom tells you where to point your browser:

http://localhost:1313/

Paste that link into your browser and behold your beautiful website! This renders live, so each change you make and save will instantly appear (thus the “localhost” in the URL). But this isn’t yet visible to the rest of the world! Let’s get this stuff up onto Github.

Adjust some configurations

A lot of how your website functions is controlled by a file in your project directory called config.toml. Open this up in your text editor to check it out.

One chance to make right away is to change the URL parameter to "/". This way, your site will take the URL of your Github pages repo. For more tips/what your config file contains, check out your theme’s documentation or Github page.

2. Deploy site to Github pages

This next part was the hardest for me when I built my site, so be sure to follow the directions carefully!

  1. Create a new Github repo called <my_website>. This is for all of your website content to go in
  2. Create a new Github repo called <user_name>.github.io replacing <user_name> with your Github user name. This will be your actual live website
  3. git clone <my_website_url> %% cd <my_website>. The URL here should be for your <my_website> repo (e.g., https://github.com/<your_user_name>/my_website.github.git).
  4. In your file browers, take all of your website’s content and paste it into the new folder that was created called my_website.
  5. Double check that the website works by running hugo server and going to http://localhost:1313/
  6. If you’re happy, stop the server by entering cntl+c and then enter rm -rf public. Commit your changes and then push them to your master branch.
  7. git submodule add -b master https://github.com/<your_user_name>/<your_user_name>.github.io.git public. This creates something called a submodule - when you build your site, the public facing content gets put into a different place (your <my_user_name>.hithub.io page).

Build your website using a shell script

OK, that was a lot of stuff. Now we need to actually build the site. We’re going to do that by writing a shell script - a mini-program you can run to tell the computer to update and rebuild your website.

First, create a file in your project directory called deploy.sh. You can do this with:

touch "deploy.sh"

Open this file up in a text editor, and paste in the following code.

#!/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 # if using a theme, replace with `hugo -t <YOURTHEME>`

# 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

Save the file and close your text editor.

To run this script and build your site…

./deploy.sh "a message for the commit"

This will build your site on the <your_user_name>.github.io page! Usually it takes a couple of minutes for the site to build/rebuild.

Now, anytime you make changes to your site, such as creating a new web page, a new blog post, adding images, etc., you’ll want to first commit and push your changes, and then run the deploy.sh script rebuild your website.

Congrats! you’re now the proud owner of a personal website, hosted for free by Github pages! Keep in mind this tutorial is the bare minimum to get you started. Be sure to read your theme’s documentation to fully leverage all of the built-in features and do some Googling to find plugins that can help you display content, etc. In future posts, I might feature how to install/use some of the tools that I use on my site.

PSA: For me, this was a learning process. A lot of stuff broke/didn’t work the first time, and I had to do a lot of Googling to troubleshoot issues and even re-start the project twice! Hang with it - it was so rewarding when I finally got things to work and was able to add neat new features to make my site look prettier and more interactive.

Happy coding! jH

Sources:

comments powered by Disqus