Create and Publish a Hugo Site

Table of Contents

In this tutorial, I’ll walk you through the process of building, configuring, and publishing your very own Hugo-powered blog. Whether you’re creating a personal blog or a different type of static site, these steps will help you to get up and running with ease.

Installing Hugo

Hugo comes in two versions: Standard and Extended. In this tutorial, I’ll show you how to build the latest extended version from the sources. Alternatively, if you prefer a quicker setup, you can install Hugo as a precompiled binary. For more details, check out the official Hugo Installation Guide and the Hugo Releases.

It’s recommended to use the extended version as it converts images to the .WEBP format and supports SASS for styling. Some themes are compatible only with the extended version.

Prerequisites

To build Hugo from source, you’ll need the following tools installed: Git, Go, GCC, and G++.

  • Install Git, GCC, and G++ on Ubuntu with the following command: sudo apt install git gcc g++
  • Install the latest version of Go by following the official instructions

Installing Hugo From Sources

To get started, clone the Hugo repository using Git and navigate into the project folder:

git clone https://github.com/gohugoio/hugo.git
cd hugo

Before building Hugo, it’s important to understand how Go handles binary installation. By default, Go installs binaries in the $HOME/go/bin directory. You can customize this behavior by setting the GOBIN or GOPATH environment variables.

  • GOBIN: If set, Go will install the Hugo binary in the directory specified by this variable.
  • GOPATH: This variable lists directories for Go to look up dependencies. Binaries will be installed in the /bin subfolder of the first directory listed in GOPATH.

For our purposes, I recommend using the default location or specifying a custom path with the GOBIN variable.

Execute the following command to build Hugo:

CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest

Once the build is complete, verify that the Hugo binary is present in the Go binaries directory:

$ ~/go/bin ❯ ls
hugo

Add the folder containing the Hugo binary to your $PATH environment variable and restart your console. You should be able to get hugo version with hugo version

$ ~ ❯ hugo version
hugo v0.134.0+extended linux/amd64 BuildDate=unknown

Creating Site

After installing Hugo, we’ll create a new site, install a blog theme, and add some content.

To create a new site, run the following command:

$ ~/workspace ❯ hugo new site demo-blog
Congratulations! Your new Hugo site was created in /home/<USER>/workspace/demo-blog.
...

Navigate to your site’s directory cd demo-blog.

Initialize a local git repository with git init.

Installing Theme

Navigate to the Hugo Themes page and choose a theme that fits your needs. For this tutorial, I will be installing the simple and clean Whiteplain theme.

To add the theme as a Git submodule, run the following commands:

git submodule add https://github.com/taikii/whiteplain.git themes/whiteplain
git submodule update --init --recursive

The theme will be automatically downloaded into the themes/whiteplain subdirectory. Each theme comes with its own installation guide and provides various properties that are unique to that theme. Always consult the theme’s documentation for detailed installation instructions and customization options.

Now, we need to replace the default hugo.toml configuration file in the root of the site folder with the one provided by the theme.

  • Navigate to the Whitepalne configuration section
  • Copy the configuration
  • Replace hugo.toml contents with the new configuration

Hugo configuration

Now you can test your site locally. In the root folder of your site, run the following command:

hugo serve -D

This will start a local server hosting your site. The -D flag ensures that any draft posts are rendered. Once the server is running, you will see the following message:

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) 
Press Ctrl+C to stop

Open the URL http://localhost:1313/ in your browser, and you should see your site with the theme applied.

Site with only configuration

Return to the hugo.toml configuration file and update any applicable parameters, such as title, copyright etc. As you make changes to this file and save them, you will see the related values update live on your site.

Site after configuration update

I don’t want to have the Archive section on my blog, so I will remove the corresponding entry from the menu by editing Header Menu section in the config file.

Removing archive

When you save changes to the configuration file, your site will automatically reload, and the Archive section will disappear from the menu. This is an example of how to edit your site using parameters in the hugo.toml file. Similarly, you can add or remove any other links in your navigation menu by adjusting the configuration.

Creating Content

Let’s create the About page for your site. According to the theme guide, we should create a content/about/_index.md file to display information about the blog or author.

Use the hugo command to create the new page:

[ master S:2 ?:5 ✗ ] ❯ hugo new content about/_index.md
Content "/home/<USER>/workspace/demo-blog/content/about/_index.md" created

Now, if you navigate to the About page on your site, you’ll see the default page layout, which includes the name from the configuration file, a Gravatar image, and various social media links. To modify these elements, edit the configuration file.

Next, update the content in the content/about/_index.md file. You can add any additional information to this file, which will be appended below the social media links on the page. Once you’re happy with the content, set the draft value to false in the file header. This informs Hugo that the page is ready for publication.

Keep in mind that any content with draft=true will be ignored during publication and will not appear on the production version of your site.

About Page Code About Page

Now, let’s create your first post! Run the following command to generate the new post:

[ master S:2 ?:6 ✗ ] ❯ hugo new content my_first_post.md
Content "/home/<USER>/workspace/demo-blog/content/my_first_post.md" created

The main page of your site will automatically update to include the new post.

First Post

Navigate to your new post in content/my_first_post.md and edit it to your liking. Any changes you make will be automatically reflected on your site.

In the header of your new post, edit the title to your desired text. Additionally, you can add categories=[] and tags=[] properties with applicable values to the header. This will automatically categorize your posts on the site.

Please note that for the Categories and Tags pages to update, you will need to restart the server. Also, don’t forget to set draft to false once you’re happy with the post.

First Post code First Post view

Publishing Site to CloudFlare

Once you’re satisfied with your blog’s content and appearance, it’s time to publish it using CloudFlare. The first step is to create a GitHub repository for your site. Alternatively, you can use GitLab.

Once your repository is ready, add it as the remote origin to your local repository and push all changes upstream. Use the following commands:

git remote add origin <your-github-repository-url>
git add .
git commit -m "Blog and first post"
git push -u origin master

After pushing your changes to GitHub, the next step is to link your GitHub repository to Cloudflare Pages.

  • Create a Cloudflare account, if you don’t already have one.
  • In the Cloudflare dashboard, click on the Add+ button in the top bar and select Pages from the dropdown.

CloudFlare add pages

On the next page, link your GitHub account to Cloudflare Pages and grant it access to your repository. This will allow Cloudflare to pull your site’s files directly from your GitHub repository for deployment. Click “Begin Setup”.

CloudFlare link github

On the following page, enter a name for your project. In the Framework preset dropdown, select Hugo. Keep the remaining settings as they are, and then click “Save and Deploy”. This will start the deployment of your site. Once the deployment is complete, you’ll find the URL of your site in the Cloudflare Pages dashboard. It will be something like <project-name>.pages.dev.

CloudFlare deploy pages

Access this address to see your site live on the internet. Please note that it might take 10–15 minutes for DNS records to propagate, so your site may not be available immediately.

Conclusion

This concludes the guide. Cloudflare’s free tier allows for unlimited traffic to your site and up to 500 deployments per month. You can easily add or edit new posts by pushing changes to your GitHub repository—Cloudflare will automatically detect these changes and trigger a re-deployment.

As a next step, you can link a custom domain to your blog and explore the additional features provided by Cloudflare.