Overview

This guide outlines the steps required to create a minimal blog like this one. This blog leverages Github Pages and Hugo to render markdown pages as blog posts and apply the Gokarna theme.

The steps will begin with setting up an account on github.com and run through to deploying the site via a github workflow. I may create another post about adding the ability for your readers to comment on a post.

Requirements

Familiarity with using a terminal
Ability to install hugo and git on your machine
Text Editor (I may look at a adding a CMS, like Netlify in another post.)

Github Setup

Login to github.com or Create a new account.
Create a new repository. (In the upper right corner, click the ’+’ > New repository.)
Name the repository [your_username].github.io (e.g., tombombadil.github.io).
Verify repository is Public.
Click Create repository.

Software

Before you can deploy your site, you will need to install hugo and git.

Install Hugo

The installation instructions differ depending on the OS you are using. Please refer to Hugo’s official documentation for how to install hugo.

Your process might look something like:

Open a terminal.
Install the package with sudo pacman -S hugo or sudo apt-get install hugo.
Confirm hugo is installed hugo version.

There is a Docker image available, if you’d prefer to add an alias to your .bashrc:

alias hugo='docker run --rm -it -v $(pwd):/src klakegg/hugo:latest shell'

Install Git

The installation instructions differ depending on the OS you are using. Please refer to Git’s official documentation for how to install git.

Your process might look something like:

Open a terminal.
Install the package with sudo pacman -S git or sudo apt-get install git.
Confirm git is installed git --version.

Setup Local Project

Open a terminal.
Navigate to the folder that will store your blog’s files, e.g., ${HOME}/src/github.com/
Run hugo new site [your-site-name].
Navigate into your project cd !!.
Run hugo new posts/hello-world.md to create a new blog post.

Also consider choosing a Hugo theme. This site uses Gokarna.

Add Git

You already installed git. To track changes to our source code and make deploying to github pages easy, let’s turn our project folder into a git repo.

From within your project folder, run git init.
Add a theme to your project git submodule add https://github.com/526avijitgupta/gokarna.git themes/gokarna.

Configure the Theme

In addition to Hugo configuration options, each theme may have its own theme-specific options. If you chose the Gokarna theme, they have great documentation on their example site. You can also checkout the configuration file for this site.

Develop the Site

Pages can be written in pure HTML (change file extension to .html) or the much lighter simpler Markdown. To start adding pages, you would:

Run hugo new posts/[post-name-here].md.
Open [project_root]/content/posts/[post-name-here].md to start editing the page.

When you create a new page with hugo, it will add some default “metadata” at the top. This metadata sets the title of the page, the publish date, the publish date, whether the current page is a “draft” (drafts are not published). Hugo and the theme you chose will also allow you to add more metadata. The metadata for this page is:

title: "How To Set Up This Blog"
date: 2023-02-05T18:00:23-08:00
draft: false
type: post
showTableOfContents: true
tags: ["how-to", "hugo", "github", "pages", "blog", "markdown" ]

You can also create “pages” as a type, include a Table of Contents, and add tags in Gokarna. See Gokarna docs for more info.

To see how your page will look when it’s published, launch Hugo’s built-in server.

Navigate to the project folder,
Run hugo server.

Alternatively, I prefer running the hugo server with a few additional options.

hugo server --environment staging --buildDrafts --navigateToChanged

You can find an explanation of these options and additional options for the server here on the Hugo site.

When you are satisfied with your page, change the draft status to “false” and run hugo in your project root, which will build all of the static files for your site and put them in the “public” directory.

Deploy the Site

To make your site live, you have a few options. The quick way is to copy the ./public folder (with the files generated by running hugo) and initialize a new git repo for that folder. You can would then add your github-pages repo (created above).

The other option is to set up a github workflow that builds the site when you push to the main branch and places the built files in a separate branch from which to serve the site.

I use the second method for this site.

Setup Github Workflows

While I found several articles that outlined how to set up the workflow, the easiest to follow was the method on the Hugo website. Their instructions use the github action created by peaceiris.

I recommend following that guide to set up the workflow. It is clear and avoids the need to set up additional github SECRETS as it automatically generates a token for you. My first “push” using that workflow did not serve the site correctly. I had forgotten to make a gh-pages branch and set it as the branch to serve the site from. Once I set the correct branch and re-deployed, the site was published as expected.

You will also need to add your github repository as your “remote” if you haven’t done so yet. You can by:

Navigate to the project root of your site,
git remote add origin https://github.com/username/username.github.io.git
Confirm git remove -v

origin  https://github.com/username/username.github.io.git (fetch)
origin  https://github.com/username/username.github.io.git (push)

Then, to deploy the site:

Run git commit -am "[your message about the current changes]"
Run git push

That’s it! That’s all you need for a simple blog site. You should now be able to view your site at https://username.github.io. If you’d like to add a custom domain, I will give some pointers in the remaining sections.

Add Custom Domain

In order to direct a custom domain to your github pages, you will need a few things:

A custom domain
Access to that domain’s DNS records (I used cloudflare)
Time (updating the DNS records can take some time)

Configure Github

The first step is to add a custom domain to the github repository hosting your site. To do that:

Navigate to your repo’s settings.
Under Code and automation, Select Pages
Enter your custom domain and click save.

I’d recommend starting with a subdomain like “blog.example.com” or “www.example.com” as not all DNS providers will allow you to direct the apex domain to github pages.

In addition to adding the subdomain to your repository’s settings, you want to “verify” your domain. I found Github’s documentation on how to do this quite clear, so I’d recommend following that guide.

Configure DNS

Login to your DNS provider.
Add a CNAME record that points to [sub].example.com
(optional) Temporarily set low TTL to see changes more quickly as you are setting things up.

Changes to Site files

In addition to setting things up on Github and with your DNS provider, you need to adjust some files in your repo.

CNAME

You need to create a CNAME file that will be served at your project root. Hugo creates your project root dynamically, so we can’t add that file directly to ./public. Instead,

Navigate to your project root.
If you don’t have a ./static/ directory, make it mkdir ./static
Add a file called CNAME (no extension) under ./static/
Inside that file, add the full custom domain you added to you Github pages settings.
Save.

config.toml

You will also need to update the base URL for your site. To do so,

Open your config.toml file (e.g., ./config/_default/config.toml)
Update any references to your site’s URL.
Save.

In Gokarna, you just need to update baseURL to equal the custom domain.

Commit your changes and push. Depending on how long your workflow takes and how long your DNS TTL is, you may have to wait a several minutes to see the final result.

How To Set Up This Blog