How to start a blog on GitHub Pages with Hugo

GitHub Pages offers a free and robust platform for hosting personal blogs. There are several static site generators available for this purpose. Hugo is particularly well-suited for technical blogs due to its performance, flexibility, and extensive theme library. This guide will be demonstrated mainly on Windows and is intended for beginners with basic familiarity with Git and command-line operations.

Steps

Create a GitHub Pages repo

The repo name must be <username>.github.io, for example, my username is celestialli, so my repo name should be celestialli.github.io.

Check “Add a README file” so that the repo will set main as the default branch.

Install Hugo

First of all: Install Git.

Go to Hugo GitHub release page, choose your platform and download the extended_withdeploy version. For example, I’m planning to use hugo on Windows and I have x64 CPU. I’ll download hugo_extended_withdeploy_0.147.8_windows-amd64.zip.

After extracting the zip file, add the .exe path to the system Path environment variable, so that we can call hugo in a terminal anywhere.

To verify your installation, run hugo version in your terminal

Create local Hugo project

Open a git bash on a desired path, run hugo new site <username>.github.io. This will create a new directory named <username>.github.io.

Configure Hugo project

We will use hugo-coder theme as an example.

cd <username>.github.io
git init
git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder

Open hugo.toml, add or change theme = "hugo-coder".

hugo server

Then you visit the output address, you’ll see your blog locally.

Host on GitHub Pages

Link your local directory to your github repo <username>.github.io. To do so, you’ll most possibly run:

git remote add origin <remote-url>

The <remote-url> can be https or ssh url. It’s up to you.

Then you follow the Hugo official guide to configure the workflow.

Then you can visit your page with <username>.github.io. Everytime you push to the main branch of the repo, a workflow will start and deploy the update to the site.

Add a post

To add a post, you can see Hugo official guide.

After adding a post, you just commit and push the update from local machine to the repo. The update will deploy automatically.

More Information

Use other themes

Go to Hugo themes. Choose one you like, and click “Download”. It will teach you how to install.

Configure your site

You may configure your site with hugo.toml. To see how to configure the site, you may see an example at themes\<your themme>\exampleSite\hugo.toml