Start A Personal Website using Hugo (with customized domain and GitHub free hosting)

Table of Contents:

• Motivation
• Building site with Hugo
• Hosting static site on GitHub Page
• Acquire a custom domain
• Conclusion

Motivation

Being a PhD student since 2014, I’ve always felt the urge to create a webpage that can demonstrate my work and ideas. Overwhelmed by the course work and research loads (also partially due to my laziness), I’ve put off this work for almost two years.
It was not until I saw Andrej Karpathy’s work of the CS231n course website when I was trying to pick up Convolutional Neural Network (CNN) through a quick scan of Stanford’s course website. In addition to the wonderful summary and explanation of CNN, I also realized that two good News about creating website:

• GitHub offers the free static site hosting through GitHub Page
• Markdown is a simple yet powerful tool to create structured content

Being a huge fan of git, I decided to try a GitHub Page website of my own. After a few trials with GitHub Page and follow the example of CS231n’s repo, I pause the project. Even though GitHub Page gives you a great flexibility to configure your website freely, it is still too much work to set up the page template and get everything going. I still see a large barrier that I saw when I was trying to create my website using HTML + CSS.

Just before I gave up the project and put off my website for maybe next year, I came across this great static site generator, Hugo that seems to enlighten the whole project. Being standalone software written in Go, it saves me from configuring and setting up all the complicated testing environment and help me dive into the site creating right away. Not to mention that Hugo is super fasting in generating pages since it is written in a static typing language (Go). Further more, the rich theme gallery offers a wide range of options to create a website in two minutes with bootstrap support.

Building site using Hugo with Academic theme

Following the YouTube video before or this tutorial, it is easy to start building site with Hugo. Some useful commands are listed here for a glance (and my future reference):

Commands	Description
“hugo”	Build your website
“hugo -t <theme>”	Build your website with <theme> downloaded in /theme directory
“hugo version”	Check hugo version
“hugo new site <sitename>”	Build a new site under current directory
“hugo new /post/blog_page.md”	Create a new post named “blog_page.md”
“hugo server -w”	Watch file system for changes and recreate as needed

A working example can be found in this quick tutorial, but here are important steps I took as milestones:

Create an empty website:

Type the following command and you will get a site named “lijun” created by Hugo:

hugo new site lijun
tree -a

Here are the results:

• Preview your template: Use the hugo server -w to preview the template under “localhost:1313”.

When the site is first created, you should see nothing under “localhost:1313”.

Choose a theme:

We choose Academic since we are trying to create a personal webpage for PhD students. You can choose whichever theme that fits your need.

git clone https://github.com/gcushen/hugo-academic.git themes/academic
cp -av themes/academic/exampleSite/* .
hugo server -w

When open “localhost:1313” now in browser, here is what you will be seeing:

Adding contents.

Now you can start the real work of creating website: adding content. Markdown language is assumed in this framework and there is a nice Markdown tutorial on Markdown syntax in the default post along with template. To better organize your content, you can check out this content managing tutorial. After update the “/content” directory with your own information, here is what you can expect:

Generate local site

You can generate the HTML/CSS file locally under “/public” directory by the following command:

hugo -t academic

Hosting your website on GitHub Page

GitHub generously offers static page hosting without content size limit. This is the ideal place to host academic personal website since there can be some cases that your personal files (e.g PDFs of your old papers) exceed the limit of free plan on other hosting service.

There are multiple tutorial out there introducing the basic techniques of hosting website on GitHub Page. Here is a short list of what I referred to:

• Hugo’s tutorial titleed “Hosting on GitHub Page”
• Jonathan McGlone’s blog titled “Creating and Hosting a Personal Site on GitHub”
• GitHub Tutorial titled “Using a custom domain with GitHub Pages”

The Hugo blog offers a nice short script that can be used to automatically deploy website. I included here for reference:

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace by `hugo -t <yourtheme>`

# Go To Public folder
cd public
# Add changes to git.
git add -A

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back
cd ..

Acquire a custom domain

Many people would prefer to have their personal website under a URL in the format of “FirstnameLastname.com” rather than “FirstnameLastname.github.io” which is the default URL for any GitHub page. In that case, a custom domain is right for you.

If you are OK with the inconvenience about HTTPS, GitHub offers this short tutorial to set the custom domain up. For automatic redirection, check out this table.

If you do not have a custom domain already, there are multiple providers that offer cheap domain. I went with Google Domains for its simplicity. You can certainly pick any of them such as GoDaddy and NameCheap.

Conclusion

With the recent development of static site generator and GitHub Page, you can easily set up a personal site in a Sunday afternoon. The git-based deployment is very much in favor of my git-centric working flow.