16:00 – 17:00, Thursday 11 October 2018, LSK 121.
Learn how to get up and running with Hugo, a popular open-source static site generator that’s fast and easy to use. Attendees can follow a live coding session to learn how to generate and customize a brand new Hugo website. We’ll learn how to host the website from a GitHub repository using GitHub Pages. Time and interest permitting, we’ll explore how to host the site on a custom domain (like asberk.ca). This tutorial is the perfect starting point for breaking away from the frumpy academic webpages of yore, and attracting those shiny impressions that’ll make your Google Analytics page sing.
To be completed by attendees before the tutorial:
- Install hugo (e.g., using
brew install hugo). If installed correctly, running
hugo versionin Terminal shouldn’t return an error.
- Have a GitHub account (it’s free to sign up)
- Ensure git is installed. If installed
git --versionin Terminal shouldn’t return an error.
- (Optional) Have an account with a domain registrar (e.g. Google Domains, Namecheap, CIRA, etc.)
This tutorial claims absolutely no originality. It is merely a curation of the four articles below, designed so that virtually anyone in attendance can get a website up and running in one hour.
For more details than what’s covered in the tutorial, Hugo offers a Quickstart Guide and a post covering Basic Usage. In addition, there is an article about hosting on GitHub and about hosting on a custom domain.
Finally, here are three registrar options for securing your own domain.
brew install hugo
- Make sure hugo works by running
hugo versionin Terminal.
hugo new site quickstartto create a new Hugo site in a folder named quickstart. e.g., I’ve created mine in
- Make sure you have a new repository for the site on GitHub
Get the example site into a repository
cd quickstart git init git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke git commit -m 'add theme submodule' rm config.toml cp -r themes/ananke/exampleSite/* ./ # -> change theme name to theme folder name # -> remove themesDir variable # -> change baseURL to http://quickstart.aaronberk.ca emacs config.toml git add * git commit -m '[IC] example site' git remote add origin email@example.com:asberk/quickstart.git git push -u origin master
Now we need to get this thing hosted on github pages.
# master must ignore gh-pages branch echo "public" >> .gitignore git add .gitignore git commit -m 'add .gitignore' git push # initialize gh-pages branch git checkout --orphan gh-pages git reset --hard git commit --allow-empty -m 'initializing gh-pages branch' git push origin gh-pages git checkout master # build and deploy using worktrees rm -rf public git worktree add -B gh-pages public origin/gh-pages # --> build site hugo cd public && git add --all && git commit -m 'publish to gh-pages' && cd .. git push origin gh-pages
That’s the coding bit.
Finally, we need to go to GitHub and Namecheap to finagle with some things. First Namecheap… Once you have a site, click on Manage Then click on Advanced DNS GitHub requires that you enter these two IPs as A Records. If you wish to use a custom URL like quickstart.aaronberk.ca then you must enter a CNAME record for it.
And next the settings on GitHub. First go into Settings. Scroll down to set the custom domain field to your site. Then click Save.
You should now be able to go to your shiny new website at
How do you make changes to your website? Here are some tips
hugo serveris your friend — let’s you preview what’s going on before you publish. Even refreshes every time you save changes.
- Useful shortcuts like
hugo new post/myNewPost.md
- Look at the theme documentation for its full set of features — sometimes there are many!
- Use the
publish.shscript from the tutorial (or a slightly modified one). The only caveat here is that this doesn’t actually do the final
git push origin gh-pagesthat you need, so you can add it in at the end to make sure it auto-pushes for you. Or don’t, in case you don’t want it to have that much power. 🐧