Hosting your blog on Github Pages using Hugo

If you want to create a new blog / or want to host your blog site then it’s worth taking a look at Hugo.

Hugo is a free static site generator.

You can install Hugo by following these steps from the docs: –
https://gohugo.io/getting-started/installing/

Once installed you can run your content locally first which means you create content and see the change with a live reload – instant feedback on your changes which means you can create content to your liking rapidly.

The content is created using markdown and if you’re looking for a nice tool to help with markdown I was recommended to take a look at stackedit.io https://stackedit.io/app#, but tools like Visual Studio Code offer this also.

I am going to assume that you have installed Hugo and have some content.

To run the website locally type hugo server

This normally shows you a screen like so:-

We can see the url to use (highlighted in red) so grab this url http://localhost:1313/ and paste it into your favourite browser and there you can see your new creation. (Keep updating the content and testing it out until your happy with all of the content.)

If your planning on hosting your site using GitHub Pages then you need to make a small change to the config of your Hugo site, locate the config.toml file within the root and add in the following line just before the [params] section (normally line 8 maybe 9)

publishDir = “docs”

For the cloudfamily.info project which we host on GitHub Pages our config.toml file looks like this

This file and all our code for reference can be found at https://github.com/CloudFamily/CloudFamily/

Note:-

Before we added the change to the config.toml the code would be compiled into the newly created public folder,

If your planning to host your Hugo site on Azure then come back for part 2 and I’ll show you how to host your new blog using Hugo on Azure.

I’m going to assume if you’ve gotten this far Hugo has perhaps sparked some interest, or you’re looking into moving to use GitHub Pages.

Create a new repository in GitHub and upload all of your content from the root (including the docs folder, p.s. assuming you’re still pushing to GitHub Pages).

To activate GitHub Pages with the new repository you need to go to the Settings section within your new repository and make the same change as in the image below. (change the source drop-down to point to the /docs folder)

Once you have completed that step, you need to go back to the root of your repository within GitHub and look for the environments link like the image below: –

This is where the GitHub Pages are compiled and built essentially, click on this link and you’ll see the latest code being built like so: –

And once that passes, click on View deployment to see your new site in action.

Note: –

You may notice that there are some issues with the look of the site, there are 2 things to check in order to resolve.

---

Potential Issue 1

First, add your website URL from the browser into the top line of the config.toml file like so (changing out username and repository name for either the URL or your website name if you have a custom domain name).

baseURL = “https://<username&gt;.github.io/<repository name>/

So for the https://cloudfamily.info/ website our top line in the config.toml file looks like this:-

baseURL = “https://cloudfamily.info&#8221;

Once you make this change, go back to the command prompt or PowerShell and run the command from the root folder Hugo

This recompiles your changes, then cd into the docs folder and do the following:-

• git add.
• git commit -a -m “updating config.toml file”
• git push -u origin master

---

Potential Issue 2

Depending on what theme you chose, you may have to add it in as a submodule, an example of this is if you chose the minimal theme then you have to run the following command from the root folder of your repo:-

$ git submodule add https://github.com/calintat/minimal.git themes/minimal
$ git submodule init
$ git submodule update

Once you make this change, go back to the command prompt or PowerShell and run the command from the root folder Hugo

This recompiles your changes, then cd into the docs folder and do the following:-

• git add.
• git commit -a -m “updating config.toml file”
• git push -u origin master

---

That should be you up and running, just remember the following if you make changes and want them to be compiled and ran on your GitHub Pages: –

Go to the root folder within the command prompt or PowerShell

• Type Hugo to compile
• Change dir into the Docs folder and then
• git add.
• git commit -a -m “updating config.toml file”
• git push -u origin master

Note – many thanks to people who have pointed me in the direction of Netlify and other tools, I’ll look at Netlify next and the next post will cover hosting a Hugo site in Azure.

Please get in touch if you have issues with Hugo.