How to host Hugo blog on Github Pages for free

The newest static page generator blows Jekyll out of the water. Learn how to host it for free on Github pages.

Natasha Pristovsek

5 minute read

Why Hugo

I know what you’re thinking…why do we need a new static generator, what’s wrong with Jekyll. Well, look, I love Jekyll… but playing around with Hugo for a week … it blew Jekyll right out of the water. Let’s first check out why Hugo in case you are just entertaining the idea of switching to / using Hugo.

the good, bad and the ugly

Reasons for going Hugo:

  • Simple theme handling. You can create and switch between different themes in one blog without creating a mess.
  • Live reload (see changes to your site immidialtely as you are making changes in code). This is true for both for content and non-content files. They are constantly tracked, updated or reloaded live in browser.
  • It’s super fast. (Way faster than Jekyll).
  • Great gor beginners (easy theme selection, live reload and very simple setup)
  • Great for pros (can concentrate on the content, everything works fast, great for large blogs)
  • Fast growing community. Although very young, Hugo already has a vibrant and growing community.

Hugo Drawbacks:

  • Jekyll has been around for longer and therefore offers more extensability than Hugo does (for now).
  • It’s written in Go (not the most popular of the languages but still easy to learn)

The ugly:

  • Hosting on Github pages is (a tiny little bit) less straight forward than with Jekyll. (But with the help of this blog post, that’s not a problem either)

If you’ve decided to try or switch to Hugo, the rest of the article will guide you through the process of hosting it on Github. Setup will be different for those of you that already have a repository with the blog and those creating it for the first time.

Host your Hugo blog on Github Pages

So let’s get this party started! Before starting, kill hugo server if running, so it stops generating content in public folder and doesn’t mess up our setup.

1A. Create two repositories

Follow this step if you have not commited anything prior to this yet (otherwise skip to step 1B).

Go to Github, log into your account and create:

  • one new repository named “OTHER”
  • one repository named “HUGOBLOG”. This one will be used to publish your blog content on github pages and should be “initialized with a README” option ticked on.

(Of course, you can name these two repository as you wish, just don’t mix them up during the next steps)

Now move on to the 2nd step, where we will type few simple commands in the Terminal.

2.A Add remote origin for the “hugoblog” repository

For this next step, hit up the Terminal and hop into the folder with your hugo blog by using cd (move inside a folder) or cd .. (move outside of the current folder) commands. Then use git init command to initiate git tracking and add a remote ( created in the first step) repository.

$ cd HUGOBLOGFOLDER
$ git init
$ git remote add origin git@github.com:USERNAME/OTHER

1B. Create one repository and remove public folder from git tracking

Follow this step if you have already commited and pushed blog before (if you’ve just finished step 1A, skip to 2nd).

  • Go to github.com and create: One repository named “HUGOBLOG”. This one will be used to publish your blog content on github pages and should be “initialized with a README” option ticked.
  • Move to terminal and delete “public” directory from git (Of course, you can name these two any way you want)
$ git rm -r public

3. Clone hugoblog repository into a public submodule

We’re now going to clone hugoblog repository into a submodule in public folder as the public folder is the one where Hugo blog generates your entire blog

$ git submodule add git@github.com:USERNAME/HUGOBLOG.git public

4. Add, commit and push to origin on Github

$ git add .
$ git commit -m"initial commit"
$ git push -u origin master

5. Deploying to Github

$ hugo -t THEMENAME
$ cd public
$ git add .
$ git commit -m "generated blog"
$ git push origin master

6. Change settings in Github repository

  • Go to HUGOBLOG repository on Github and click settings.
  • Move to GitHub Pages section of the options and under Source select Master branch in the drop down menu. This tells Github pages where to look for files that make up your blog.

7. Add costum domain

  • Go to your “HUGOBLOG” repository on Github. Go to settings–> Github Pages area –> Source set as “master branch” and click save.

github pages

  • In the “custom domain” area type your desired domain and save.
  • Now all you have to do is visit your domain provider website and access “manage DNSs / DNS zone or similar” area.
  • Add two new records. One CNAME(Alias) with host *“www” pointing to your blog “USERNAME.github.io” and one A(Host) with host ”@” pointing to 192.30.252.153. (see example images bellow from GoDaddy DNS Zone settings).

Github hosting DNS custom domain Github hosting DNS custom domain

If you already have another site that points to your github repository your internet provider will not allow you create another CNAME record pointing to it. In this case simply create two “A” records one pointing it 192.30.252.153 and other at **192.30.252.154.)

  • Save changes. It might take from 5 min to 48 hours for this change to come into effect and for you to see your blog on desired domain.

8. Volla, how bout simplyfying deployment now?

Everytime you want to push changes to your blog / website, you will have to repeat 5.th step (it can be howeverautomated using various scripts). Locally you can edit your website by simply typing “hugo server” command to see changes locally live.

$ hugo server

Visit your local site in browser at URL localhost:1313 . When ready to publish, move out of the public folder in terminal and follow the 5th step all over again.

This is it! You’re now hosting your blog for free!

comments powered by Disqus