Logo kepa.eu.org

setup static page with hugo, github pages and custom domain

Nov 1, 2024 - 5 minute read

preface

In this series of brief tutorials, I will show you how to generate a simple static website, host it on GitHub Pages with a custom domain, and do it all for free.

I’ve noticed many people using Medium to share their ideas, and it’s a fantastic platform. The concentration of brilliant techies posting their thoughts and solutions is truly impressive. However, what about those who want to build their own brand, promote their own domain independently, and avoid getting lost in the crowd? While it’s important to promote our site through various channels to achieve the best rankings, we can still host our small projects on our own domain where we have near-complete control.

steps

install hugo

To start creating your page, we first need to install the Hugo environment. There are various static page generators like Jekyll, Next.js, and Gatsby.

My goal was to be quite versatile. The benefits and ease of use when creating a website comes down to creating the proper Markdown files, which is both easy and awesome! I chose Hugo after digging into multiple sources and receiving good feedback, as well as the extensive marketplace of themes.

Hugo is blazing fast and is supported on many platforms and through multiple package managers. I personally use Ubuntu Linux as my base host, which is supported out of the box.

Whole setup details, including repositories, can be found under this link.

Keep in mind that Hugo requires Golang version 1.22 or higher and sometimes the dart-sass package for proper CSS transpilation.

create a simple website

The documentation steps can be found under this link.

After installing Hugo, you can check if it’s ready to go by following these steps:

  • Create a website with YAML as the starting config format (TOML is the default).
  • Navigate to the folder of your website and init repo.
  • Add the initial theme through a git submodule.
  • Add the theme name to the base config.
  • Run and check the output.
hugo new site demo --format yaml
cd demo && git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme: ananke" >> hugo.yaml
hugo serve

Navigate to the link from the CLI output to check the results, which by default is http://localhost:1313/ If the port is already taken, you will get a random port from the high port range (30000+).

Your whole statically generated page is in the ./public folder within the demo directory. From here, you can take it and publish it wherever you like.

Keep in mind that if you did not stop the hugo serve command, all changes will be reflected immediately after saving any config or site files.

install theme

⚠️ This part can be tricky since each template works differently! Some templates work directly via a git submodule add or the hugo mod get command. Others need to be copied or cloned directly from the template creator’s Git repository.

First, choose your favorite theme from the official site https://themes.gohugo.io/. Then, navigate to the details of the theme and follow the instructions provided in the description!

After you have found it and properly installed and configured the details, give it a try and run the hugo serve command!

own domain

If you already have your domain, you can skip this point.

I have the privilege of having my domain registered with nic.eu.org, which is completely free of charge and leased for 100 years.

To register your own domain, please follow the instructions from this link.

Keep in mind that since this is an unpaid service, any kind of help is welcome, and the request can take some time. I waited around two years for mine, but that was more than ten years ago. It’s still worth it!

domain parking

To complement the open-source project of domain registration, I use the freeDNS 42 service https://freedns.42.pl/ where I parked my domain. It works brilliantly, and I can highly recommend it!

point your origin to GitHubPages

If you have your own domain registered already, inside your DNS settings point the A/AAAA or an ALIAS record of the origin @ to the following IP addresses:

# IPv4 (A)
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

# IPv6 (AAAA)
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

An example dig anwser

# get A records
$ dig +nocmd +noall +answer www.kepa.eu.org A
www.kepa.eu.org.	6883	IN	CNAME	kepa.eu.org.
kepa.eu.org.		6883	IN	A	185.199.110.153
kepa.eu.org.		6883	IN	A	185.199.111.153
kepa.eu.org.		6883	IN	A	185.199.108.153
kepa.eu.org.		6883	IN	A	185.199.109.153

# get AAAA records
$ dig +nocmd +noall +answer kepa.eu.org AAAA
kepa.eu.org.		6917	IN	AAAA	2606:50c0:8001::153
kepa.eu.org.		6917	IN	AAAA	2606:50c0:8003::153
kepa.eu.org.		6917	IN	AAAA	2606:50c0:8000::153
kepa.eu.org.		6917	IN	AAAA	2606:50c0:8002::153

At a later step, when registering the custom domain in your GitHub repository, you will be asked to add a TXT record to verify that you are the owner of the DNS origin. This is a common process for many providers, so there’s no need to worry.

redirection with www+yourTLD

Please don’t forget to create a CNAME record inside your DNS Zone for your custom domain with www in front!

This will allow you to reach your website not only with the domain (TLD) but also with www.

For example, you can reach my website at kepa.eu.org as well as www.kepa.eu.org. Many forget about this, but it’s quite handy and eliminates potential issues with link forwarding!

Example anwser from dig

# get CNAME records for your www+tld domain
$ dig +nocmd +noall +answer www.kepa.eu.org CNAME
www.kepa.eu.org.	7119	IN	CNAME	kepa.eu.org.

next steps

Okay, this post turned out longer than expected. I wanted it to be detailed so I could guide you step-by-step without leaving too many questions.

In my next post, I’ll show you how to properly set up a GitHub repository to use a custom domain and secure it with SSL certificate.