How to Create and Host a Website with Hugo and GitHub Pages

GitHub Pages + Hugo

8 min readJun 18, 2023

Introduction

Are you ready to take your website creation skills to the next level?

In this comprehensive guide, we’ll walk through the process of building a sleek, modern website using Hugo, a lightning-fast static site generator, and hosting it effortlessly on GitHub Pages. Whether you’re a seasoned developer or a newcomer to web development, follow along to unleash the power of Hugo and GitHub Pages! I’ll also show you how you can create a custom domain to give it that unique touch.

This is an update from an earlier post “Hugo in 10 Minutes”

At the end of this post, we will have a (Hugo) blog running here, deployed with GitHub Pages.

Prerequisites

Before diving in, ensure you have the following:

A GitHub account
Hugo installed on your system
Basic familiarity with Git and GitHub Pages

Setting Up GitHub Pages

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

In addition to that, it’s also free.

Follow these steps to get started:

Create a new repository named <username>.github.io to publish your user site.
Clone the repository to your local machine.
Add an index.html file to your repository.
Commit and push your changes.
Enable GitHub Pages in your repository settings.
Within a few moments, your website will be live at https://<username>.github.io.

Note: Refer to GitHub’s documentation for any limitations, you can find that here.

Getting Started with Hugo

Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again. It is a popular static site generator, designed to provide an optimal viewing experience for your website’s end users and an ideal writing experience for website authors.

A static site generator is a tool that generates a full static HTML website based on raw data and a set of templates.

Hugo works on macOS, Linux, Windows and you can follow the installation instructions for your platform here.

Let’s kick off your Hugo journey:

Install Hugo on your system by following the instructions for your platform.
Create a new Hugo project by cloning your GitHub repository.
Choose a theme from the Hugo themes library or create your own.
Customize the theme to match your preferences by modifying the configuration files.
Add content to your website by creating new posts or pages.
Preview your website locally using Hugo’s built-in server.

Deploying Your Website

Once you’re satisfied with your website’s design and content, it’s time to deploy it to GitHub Pages:

Clone your repository to your computer: git clone git@github.com:magsther/magsther.github.io.git
Navigate to the folder and run: hugo new site ollycloud -f yml
Follow the additional steps provided.
Visit Hugo’s website for a quick start guide and full documentation.

Themes

Hugo offers a variety of themes for your website. Select a theme that suits your style and follow the instructions to install it.

If you are familiar with Wordpress then you will know how useful this is. Let’s first to go the themes page and select a theme that you like.

I like the PaperMod theme, so I’ll use that one.

Installing a Theme

Follow the instructions for the theme on how to install it. You can also watch a YouTube video where the author will guide you through the process.

When you select a theme it will give you instructions about the installation and configuration for that particular theme.

I cloned the repository and copied the PaperMod themes folder into the root themes folder

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

I also replaced the config.yml file (in the root module) and made some changes to it.


baseURL: "http://magsther.github.io/"
title: O11yCloud.com
paginate: 5
theme: PaperMod
...
....

Run Hugo

To view the website locally, we can use Hugo’s development server. Just type in hugo server at the prompt, and it will start building the website. At the bottom of the output we can find a link on how we can access the website.


Start building sites …

                   | EN
-------------------+-----
  Pages            |  7
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Built in 32 ms

Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Open a browser and go to http://localhost:1313

Making changes on the “fly”

Modify the config.yml file to see real-time updates on your website while Hugo's development server is running.

This happened, because the Hugo process was still running in the other terminal and will build any changes that you make.

Change of config file detected, rebuilding site.
2023-06-11 23:15:55.936 +0200
Rebuilt in 63 ms

Tips, if you run hugo server -D then it will also included any posts that are in “draft” mode.

Adding content

Create new content for your website by adding posts or pages. Use the provided templates and commands to streamline the process. For example, I first added a post.md file that was provided in the repository to the archtypes folder. You can think of that file as a template for all future posts. To create a new post, I typed in hugo new posts/example.md

This added an example.md file in the content folder.

You can now open this file with your editor to create your blog post.

If the Hugo process is still running and you are using the -D flag, then you will see that a new blog post is now added to your website.

Once you are done with the changes to your post, you can change draft: true to draft: false to have it deployed. This is depending on the theme you are using. If you are using the default theme, then Hugo does not publish draft content when you build the site

This should give you an understanding on how to create new blog posts.

Customizing Hugo

Tailor your website further by adjusting settings in the config.yml file located in the root folder.

The first things that you probably want to change are the baseURL, title and the theme

baseURL: "https://magsther.github.io/" #This value must begin with the protocol and end with a slash, as shown above.
title: O11y Cloud.com
paginate: 5
theme: PaperMod

Publishing your Blog to GitHub Pages

When you’re ready to share your website with the world, generate the blog using Hugo and push the changes to GitHub. Enable GitHub Pages in your repository settings to make your blog accessible online.

To do that, we need to run hugo to generate the blog. That will create a docs folder that you will need to add an entry for in the config.yml file for.

After that, we add, commit and push them to the GitHub repository.

git add . && git commit -m 'new hugo blog' -a && git push

Next, we need to enable GitHub Pages, which we can do by going to our GitHub repository and from there click on Pages.Enable it by changing the Source from None to Deploy from a branch

Save your changes.

After a short while, you will see that your blog is now published at https://username.github.io

GitHub Actions

GitHub Actions automates the process of rebuilding and deploying your website whenever changes are made to the repository.

If you click on the workflow, you can see a summary of the jobs that are part of this workflow.

In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes.

Updating your blog

To add new posts and publish them on your website, follow the provided workflow.

Create a new post with hugo new posts/example2.md
Build the site with hugo
Add, commit and push the changes to GitHubgit add . && git commit -m 'creating my second post' -a && git push
Watch the workflow in GitHub Actions
New posts are published at https://username.github.io

How to add a custom domain to GitHub Pages

Now, let’s take our website a step further, and give your website a unique identity by setting up a custom domain name using GitHub Pages.

GitHub Pages supports using custom domains, or changing the root of your site’s URL from the default, like octocat.github.io, to any domain you own.

Getting Started

To kick things off, I added a CNAME record that links our subdomain to the default domain for our site using my DNS provider. It’s important to note that this CNAME record must point to <user>.github.io.

The next step is to integrate your domain into your GitHub account. You can find detailed instructions in the official documentation.

Navigate to your Settings and select Pages.
Scroll down to the Custom Domain section.
Enter your domain name and click Save. You can also opt to enable Enforce HTTPS for added security.

Once these steps are completed, you’ll notice that a CNAME file has been automatically generated in the root of your repository. Make sure not to delete this file!

You can use the dig tool to verify that the DNS record is correctly configured. Simply run the command dig www.o11ycloud.com.

Note: DNS propagation may take up to 24 hours.

To confirm that everything is working as intended, open a new browser and navigate to https://www.<your_domain>. For instance, I visited https://www.o11ycloud.com/.

Conclusion

You’ve successfully created and hosted a stunning website using Hugo and GitHub Pages. With your newfound skills, the possibilities for your online presence are endless. We also integrated a custom domain name into our website using GitHub Pages.

This blog post was also posted on my O11yCloud.com blog which is hosted on GitHub Pages.

If you find this helpful, please click the clap 👏 button and follow me to get more articles on your feed.