In the first part of this three-part series, I’ll guide you in setting up a simple blog like the one you’re on right now, and show you how to host it for free on Github Pages. When I began on this journey myself, I had close to zero experience with Github. I followed some of the available guides already out there on the web, (including those from Hugo themselves), but there were some parts that didn’t quite click with me right away and it relied upon a lot of time and trial & error before it all finally worked.
In this series, I will assume you have close-to-zero experience with setting up websites or with Github, but by the end, I hope you will understand exactly how to work with Hugo, and understanding more clearly some of the broader concepts in using Git, and then finally, I’ll show you how to customise your site, and create the workflow for pushing content out to your blog in a quick & efficient manner.
Note: This guide is written from the perspective of a Mac user, but the general workflow should be roughly the same across all platforms, although some CLI commands will most certainly differ.
I’ve always wanted to write my own blog since the early days of the internet, but none of the available platforms appealed to me. I really didn’t want to use a “pre-rolled” solution like Blogger.com due to lack of customisation and Wordpress just felt too much. What I needed and wanted was something in between those two extremes and Hugo is it.
Hugo is a static website generator with theming support as opposed to a dynamic site generator like Wordpress. This means that instead of your site being generated on-the-fly from a database, all your pages are served as plain HTML and CSS. It also means that your site is delivered to the end-user blazingly fast. I loved the idea of generating static sites again, bringing me back to the earlier days of site creation and that Do-It-Yourself feel.
I did try operating a Wordpress site on multiple occasions in the past and while it’s easy to set up, I found the main aspects of its customisation to be utterly incomprehensible and I consider it to be — putting it lightly — hugely bloated. There are also many costs involved if you want to engage with any of the customisation options available in the form of themes or plugins. Not to mention the costs involved in procuring a domain and hosting of the site, backed by a full-blown database. Due to these factors, my desire to operate a blog actually fell by the wayside for a number of years.
Paying for hosting is not something I wanted to do as I’m not expecting to generate an income from my blog. Instead, it’s a place for me to gather my thoughts and share some interesting ideas and information. Hosting in general isn’t cheap for a Wordpress site, even though the software itself is free and open-source, the hosting alone could easily end up costing you hundreds of dollars per year. This immediately puts you under pressure to monetise your blog instead of just focusing on the content.
When I found out you can host your static site on Github Pages for free, delivering pages to the user from Github’s fast SSDs, I was completely sold.
Speed of content delivery to the end user through the use of static is pages is one of Hugo’s greatest strengths, and while I’m aware that there are numerous plugins available on Wordpress that aim to pre-compile pages for faster delivery – and this is a very valid point in favour of Wordpress– I still never did feel confident in relying upon Wordpress as the foundation for my site. Of course, I may be in the minority here, because Wordpress drives a massive percentage of all the sites across the internet, but for a simple blog like this one, Wordpress is most certainly overkill.
Well, enough about all that, you’re probably here because you already know you’d like to have a static site, so we’ll move on.
The Quick Start guide from Hugo is actually quite good, so much of the information from that guide will be re-iterated here. If you are already comfortable with the Terminal or already have your Hugo site set up, you may not need this part of the tutorial at all.
To begin, the very first thing you want to do is open up your Terminal (AKA CLI). You can do this by pressing
cmd + space on your keyboard to bring up Spotlight Search, and begin typing
terminal. When the application shows, just press
enter and up pops the Terminal.
If you’re interested in why my Terminal may look slightly differently to yours, please refer to the bonus tip at the end of the article: Terminal Navigation 101. You will also find some other hints and tips for getting started with Terminal.
Everything in Hugo is done through the Terminal (AKA CLI), so it’s a good idea to get yourself familiarised with this application.
1. Install Homebrew & Hugo
To install Hugo, you first need to install a package manager. Homebrew is the name of the package manager we’re using here. Just copy and paste the following code into Terminal…
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
enter to begin installation, and wait for the installation to finish.
When that’s done, it’s time to install Hugo. This is done by typing the following into Terminal:
brew install hugo
2. Create Your Site
We’re going to assume you’re in your
Home directory, but if you want to create your site elsewhere, just navigate there. Again, you can refer to Terminal Navigation 101 to understand this better.
To create a new site called “blog” (you can call it whatever you want) just enter this command into Terminal:
hugo new site blog
And just like that, your new site is created. Now, if you navigate to your
Home folder in
Finder, you will see a new folder called “blog” there. This is where all the code and files of your site resides.
This is just a raw template for your site right now, and [in theory] if you go to the site in your browser, you’ll see nothing but a blank page. So, you need to add a theme.
3. Add a Theme
To add a theme, you first need to visit the following website: themes.gohugo.io
Once you find the theme you want to use, you need to copy the
Download URL from the
Download button on the theme’s homepage.
For this tutorial, we’ll use the Hermit theme.
The URL from the
Download button is:
Note: This URL ends in
.git. This is important.
Once you’ve got this URL,
cd into the
blog/ directory you just created by using this command:
Now comes your first interaction with Git through the command line.
Note: Recent versions of macOS have an Apple fork of Git already installed as standard. If your installation doesn’t have this, type
brew install gitand wait for the installation to finish.
Type into Terminal:
git submodule add https://github.com/Track3/hermit.git themes/hermit
What these two commands are doing is first initialising a local Git respository based on your
blog folder and then you’re adding a “submodule” of the theme into your
themes folder. A submodule is Git’s way of creating a copy of a respository within another respository, which in this case, is your site folder:
blog. This makes it very easy for you to keep the theme up to date by updating the submodule, but what we’re doing here now is just taking an image or clone of your chosen theme and copying it into your
The final step in using this theme is by following the instructions in the
readme.md file included with the theme you just downloaded. Every theme will include a
readme.md file with basic installation instructions, and this theme is no different. You’re asked to copy the
config.toml from the theme’s
exampleSite folder into the root of your Hugo site. You can do this manually through
Finder or just simply use the following command:
cp themes/hermit/exampleSite/config.toml .
NB: Be sure you copy the whole command, including the
space + . at the end.
config.tomlis where you configure your site’s title, copyright information, etc. This last command will replace the default
config.tomlfile with the custom one from the theme. You could take a look inside this file right now, and make your own customisations, but I recommend doing that later, once you’re finished with this tutorial.
4. Create a Post
You can quickly create a new post for your blog through the CLI by using the following command:
hugo new posts/my-first-post.md
This creates a file called
/blog/content/posts/ and is your actual blog post. You can edit this file with any regular text editor, such as
All the custom content you create for your site will reside in this
.mdfile extension means this is a markdown file. Markdown is a very simple and lightweight markup language that easily lets you format your blog posts with very minimal syntax, through any plain text editor. Hugo uses markdown extensively to format your posts. Getting into markdown is beyond the scope of this article, but there are many guides elsewhere online for you to learn markdown. Markdown Cheatsheet is one such example for a quick reference on markdown. The standard-bearing documentation at Daring Fireball is also highly recommended reading.
5. Start the Hugo Server
You start the Hugo server by using the following command in Terminal:
hugo server -D
-Doption means the server will also show any draft posts you may be writing. In this case,
my-first-post.mdis a draft. If you look at the top of your
my-first-post.mdfile, you’ll see
draft: true, meaning this post has a draft status. You publish the article by changing
false. If you run the Hugo server without
-D, your draft posts will not show.
Now, in your browser, visit:
Voilà, your site.
Hugo server is always checking your
blog folder for any changes that you make to any files and will update automatically whenever you make those changes. To stop the server at any time, just press
ctrl + c in the Terminal.
This concludes the first part in our three-part series in getting your site set up in Hugo. In your own time, have a look around the files that came with your theme, edit the
config.toml with your own information, try installing different themes, write a couple of posts, etc. The best way to learn is by having a play around yourself. I’m sure you’ll have found creating the site extremely easy, so don’t be worried about breaking anything. At this stage, you should be experimenting a little bit and if worse comes to worse, you can start over. Just make sure to protect your
content folder, because again, this is where the bulk of your custom content is.
Check back in next time for the next part of this tutorial where we’ll delve into exactly how to have your site hosted on GitHub Pages. See you!