Now, you decided to create a blog and you decided to use a Static Site Generator to do it. You might have read my article about creating a theme for Hugo and decided to use Hugo to create your blog. The next step is to host it.
This article is exactly about that, hosting a static webpage. I will first generally explain how to host a static website with GitHub Pages. Then I will look specifically at how to host a Hugo website and make content and theme updates a lot easier by using GitHub Action.

GitHub Hosting

GitHub offers a service for hosting static websites called GitHub Pages. To use it you do need a GitHub account. The use is free and GitHub also offers a free domain. The domain will be username.github.io. It is, however, also possible to use a custom domain.

How to set up GitHub Hosting

1. create a repository called username.github.io You might notice, that this is also the name of the free domain, GitHub provides. Make sure that you don’t have a typo!
2. create your content (-> the main page should be called index.html) -> you hosted your first website -> go to username.github.io to see if it worked
3. (Optional) If you want to use your domain name, you have to add a ‘CNAME’ file with the name of your website.

For more information, check out the GitHub Docs.

Hugo Site on GitHub

Now, that you know, how to set up GitHub Pages, let’s talk about Hugo specifically. There are two ways, to use Hugo with GitHub. One way is rather easy and should work with any kind of static hosting site. The other option uses GitHub Action to automate.

Simple Way

The simplest way to get your static site hosted is by manually putting the content of the ‘public’ folder into your repository. The ‘public’ folder is the actual website created by Hugo. To generate the folder you need to use the following command in your Hugo project folder:

1

    hugo

The ‘public’ folder will be generated. Now you can either set up a git repository inside this folder, which could cause problems if your project folder is already a repository, or you copy+paste the content of the ‘public’ folder into your ‘username.github.io’ repository. Now, if you want to use Hugo to create a blog, this means you constantly have to delete, regenerate and then copy+paste the public folder. Long-term, this is probably very annoying. There is a way, to automate these steps.

Advanced Way

To not constantly have to manually generate the public folder and potentially copy-pasting it into your repository, you can set up a GitHub Action to do it for you, every time you push new content or make changes to your website.

What is GitHub Action

GitHub Action makes it possible to automate your workflow. It makes it possible to execute code in the repository to test, build, deploy and more.

Automate deploying a Hugo Site

With GitHub Actions, it is possible to automate deleting and generating the public folder right into your ‘username.github.io’ repository. All you will need to do is push the newest changes to your repository with your Hugo project. I found a blog post, that explains the steps pretty good. However, following the steps, there were some things I wanted to highlight.
For this to work probably, it is important that you have two repositories. The first repository contains the ‘raw’ Hugo project. The second is your ‘username.github.io’ repository and only contains the content of the public folder (and optionally the ‘CNAME’ file). Every step from creating a GitHub token revers to the Hugo project repository.
The creation of the GitHub Action can be done manually by creating a ./gihub/workflow/main.yml in your text editor. However, I found using the Action tap on the GitHub page easier. It also gives you visual feedback, when the action was finished and if and why the action failed.

Include Hugo Theme

Lastly, I want to talk about cloning themes. To automate the deployment of the site, your Hugo project needs to be its own repository. This can lead to problems if you have a theme cloned. There are two ways to go about this.

1. Do not clone the theme

The easier way to include a theme from GitHub is, to not clone the repository. simply download the theme and unzip it in your theme folder.
The disadvantage of this is that if the theme changes and you want to have to use the newest version you have to manually upgrade.

2. Use git submodule

Alternatively, you can clone the repository with the submodule.
In the folder of your project simple use the following command:

1

	git submodule add <URL>

with <URL> being the cloning address.

You can now also use GitHub Action to automate the update. This is also explained in the blog post from Ruddra.com. The ‘main.yml’ file has to contain the following lines:

1
2

    - name: Update theme
            run: git submodule update --init --recursive

(add after ‘steps:’)

Conclusion

I introduced two ways to deploy a Hugo site with GitHub. Whereas the first solution is easier to set up, it does need more time in the long run. The second option automates the deployment with the help from GitHub Action, which makes it very practical and saves time, once it is set up.

If you have any further questions, feel free to send me an email or contact me over Twitter.