Hugo for Beginners
Github Pages is a great way to spin up a personal blog, product page or any other type of site that doesn’t require stateful application logic to be involved.
The defacto static page generator is considered to be Jekyll, which is a versatile, and extensible framework. However, being a fan of Golang I decided to go with the more gopher-friendly option, Hugo.
Using Github Pages
The way Github Pages works is to use a repo with the format:
In effect this means that a repo at something like the the following address is created:
For example, my username is
wilvk and so my Github Pages repository is:
with the repository address:
The corresponding static pages are delivered from the address:
If you have your own domain name, this can be integrated into Github Pages by going to the Settings section of the repository.
The way I set up my blog was to have one repository for the static pages to be delivered by Github Pages, and another for generating the static pages using Hugo. I have a script for generating the site and pushing the changes to the Github Pages site so I don’t have to do this manually every time.
We can see from the diagram that the build clones the
wilvk/wilvk.github.io repository inside the
wilvk/blog-hugo repository to the
./public path. It then builds the full Hugo site into the
./public path and pushes the changes back to the
An automated process
I place the following script in the base of the
wilvk/blog-hugo repository and run it to push the changes to the site:
#!/bin/bash set -x rm -rf ./public git clone https://github.com/wilvk/wilvk.github.io public hugo cd ./public git add . git commit -m "build release" git push --set-upstream origin master cd .. rm -rf ./public
set -x allows me to see any errors that may occur during the build process. Using different themes or various settings can cause Hugo to fail the build process and not push new changes to the static website repository
wilvk.github.io. Showing the full output enables inspection of this process for any errors.
Hugo can also be run with verbose output with
hugo --verbose, or even
hugo --debug for greater levels of detail in the build process if required.
The static site is built to the path
./public and so the first thing the script does is delete the
wilvk/wilvk.github.io repository is cloned into the base of the
hugo builds all the static files to the
The new static website is then ‘pushed’ back up to the repository
wilvk.github.io and the
./public path deleted so that is is not accidentally committed to the
blog-hugo repository. It may be useful sometimes to comment this line out if investigating why a build didn’t complete but most of the time it is useful to have it delete the path.
This way there is delineage between the build process and the resultant artefact, the static website.
Hugo has built-in support for Google Analytics so you can see pageviews over time, users currently viewing your site and other relevant details about your site.
Hugo also has support for Disqus so that users can comment on your blogs and you don’t have to store the comments in an application - allowing your website to remain stateless.
Google Analytics is free from Google and Disqus is also a free service. With IDs from both these services, you can turn your Github Pages into a proper blog.
The following is how I have set up my
baseurl = "https://blog.seso.io" title = "Will's Blog" copyright = "Copyright © 2018 - Willem van Ketwich" canonifyurls = true theme = "kiera" ## kiera theme settings paginate = 3 summaryLength = 30 enableEmoji = true pygmentsCodeFences = true ## Hugo Built-in Features disqusShortname = "wilvk-github-io" googleAnalytics = "UA-122351489-2" enableRobotsTXT = true builddrafts = false languageCode = "en-US" [author] name = "Willem van Ketwich" github = "wilvk" linkedin = "willvk" twitter = "wilvk" [params] tagline = "Just a dude that does stuff.. mostly with computers." ## Main Menu [[menu.main]] name = "blog" weight = 10 identifier = "blog" url = "/posts/" [[menu.main]] name = "about" identifier = "about" weight = 20 url = "/about/"
I’ll just point out a few things about the config file above.
- Your Google Analytics ID will go in the variable
- Your Disqus shortname ID will go in the variable
I am also using a custom domain name and so this is set in the variable
baseurl. The variable
cannonifyurls needs to be set to
true to enable correct redirects to your custom domain name.
Skinning/theming your site
If you are just starting out with Hugo (or even if you’re not), you may want to change the theme for your site.
To do this, the usual procedure is to:
- Clone the theme into the
- Edit the
config.tomlfile and set the theme to the name of the directory cloned into the
Some themes require specific config settings in the
config.toml file. They will usually tell you in the
README.md on the specifics of this.
Onwards and upwards
These are just a few things I have found while setting up a Hugo blog. For more info, I have found the Hugo docs are also quite useful.