Hugo Installation & Setup Guide (with Github & Cloudflare Pages)

Installing and setting up my Hugo site with cloudflare pages and github.

Installing Hugo

To start we will need to install Hugo, depending on the operating system this process will be different. I have installed it personally on Ubuntu and Windows. This is not a complicated process. Make sure you install Hugo’s extended version to support SCSS compilation, since the theme we will use requires it. For more detailed information and other methods of installation you can visit the Hugo installation guide.

There may be other ways to install Hugo that are more applicable for your project. For example, you can use the NPM package hugo-bin to include Hugo in a project that already uses NPM packages.

Windows 10/11

Since I already had Chocolaty installed I made use of it to install Hugo. I also make use of the Terminal app on Windows. Launch the Terminal App as Administrator and enter the following code:

choco install hugo-extended

It is also possible to install Hugo using Winget:

winget install Hugo.Hugo.Extended

To test if Hugo is succesfully installed we will type the following in the terminal:

hugo version

The reply should look like this:

hugo v0.123.4-21a41003c4633b142ac565c52da22924dc30637a+extended windows/amd64 BuildDate=2024-02-26T16:33:05Z VendorInfo=gohugoio

Linux Ubuntu Server

For installing Hugo Extended on my Ubuntu server I made use of Homebrew:

brew install hugo

To test if Hugo is succesfully installed we will type the following in the terminal:

hugo version

The reply should look like this:

hugo v0.123.4-21a41003c4633b142ac565c52da22924dc30637a+extended windows/amd64 BuildDate=2024-02-26T16:33:05Z VendorInfo=gohugoio

Creating a site

To create a new site run the following command in the root folder where you want your site located:

hugo new site name-of-site

This will create a new folder /name-of-site with all required files in it.

Installing the theme

I will be making use of the ace documentation theme. Use git to clone the repository to the themes directory:

cd name-of-site
cd themes
git clone https://github.com/vantagedesign/ace-documentation

Once the theme is installed the /name-of-site/themes/ace-documentation folder should contain the file theme.toml, along with all other theme files.

Configuring your hugo site to use the theme

Inside your site’s folder, /name-of-site, you will find a file called hugo.toml. This is the configuration file for your site. Open it and configure it to use the Ace theme by setting the following value:

theme = "ace-documentation"

It is also important to change baseURL = “https://example.com” in this file to your domain name. In my case this would be baseURL = “https://it-entity.com”.

Adding content

Now we will start creating content for our site, due to the use of Markdown it is really simple as you will see soon.

Live Preview

Open a second terminal in the root folder /name-of-site and enter the following code:

hugo server

Click the localhost link http://localhost:1313/ to see a live preview of you site. Any changes you save will almost instantly be visible.

Main page

Now we can personalize our personal homepage, navigate to the /name-of-site/themes/ace-documentation/content folder and copy the _index.md file. Paste this file in the following folder /name-of-site/content. Open the file with a text editor, I am using Visual Studio Code.

Change the title and description to whatever you want, mine looks like this:

+++
title = "CheekyEntity's Hub"
description = "Welcome to CheekyEntity's hub for documentation."
+++

Play around with it and see the changes appear in the browser after saving the file.

More content

I recommend you look at the /name-of-site/themes/ace-documentation/content folder for more inspiration and see how they use it. I will not go more in depth on how to customize your site.

Building and publishing site

You will need a Github account and a Domain with Cloudflare. Once you have both you can continue with the following steps.

Github

Create a new repository in Github, give it the same name as the folder of your Hugo site. In our case this would be name-of-site. I put my repository on private but if you want you can leave it on public. Create the repository and choose HTTPS. Copy the link https://github.com/yourname/name-of-site.git and save it somewhere for later.

We will also need to create a personal access token, go to the following link. Create a token, only select the “repo” checkbox. Copy the token and save it somewhere since we will need it later!

Build the site

Before we build the site it is important that we add our theme as a submodule so that we do not have problems pushing our site to Github later. Enter the following code in our root folder of the project:

git submodule add https://github.com/vantagedesign/ace-documentation

Build the site by entering the following command:

hugo

Pushing to Github

We will now push our site to Github, to do this enter the following commands but be sure to change the link to yours that we saved earlier:

# Replace the url with the HTTPS url we saved previously
git remote add origin https://github.com/yourname/name-of-site.git
git branch -m main
git push -u origin main 
# enter your personal access token instead of password if asked

# Build the site
hugo
# Push it to Github
git add *
git commit -m "Update 1"
git push origin main

In Github you should be able to see that we updated the repository!

Cloudflare

Login into cloudflare and on the lefthand site navigate to Workers & Pages. Click “Create Application” and then Click “Pages”. Here you can chose to “Connect to Git”, login and select our repository we created for the site. Select “Begin Setup”, this should take you to a new screen. Leave everything as it is and do NOT select Hugo under Framework Preset, leave it on none, this only supports some themes. Select “public” for the Build output directory and finally press “Save & Deploy”.

Add your domain

Navigate to the Workers & Pages page again. Select the application we just made (The name should be the same as your Github repository). Click “Custom domains” and setup a custom domain. Enter the domain name you bought, I recommend to add both your example.com and www.example.com. When you visit your domain you should be able to see your site.

Updating the site

Updating the site is really easy, make your changes, build your site and push them to Github using the following commands:

# Build the site
hugo
# Push it to Github
git add *
git commit -m "Update 2"
git push origin main

Thats it, thanks for reading! If you have more questions or corrections feel free to reach out to me via email.