Hugo1 is a static site generation tool written in Go. It is incredibly fast and has excellent high-level and flexible primitives for content management using Markdown and JSON.
You will learn how to create a new Hugo blog and deploy it using Cloudflare Pages. You will use the hugo CLI to create a new Hugo site and then Cloudflare to deploy your website. You must have a Cloudflare account and a Github account to create a new blog.
In this small section, I will try to explain how it all works. It will seem like magic at first, but once we get to grips with the fundamentals of the infrastructure we will set up, it will be very easy to create and deploy websites.
For those unfamiliar, Cloudflare is an American company that deals with DNS and reverse proxy management services. In the last year it has made available a service called Cloudflare Pages that allows you to do website deployments.
“To “deploy” means to release or distribute content within an infrastructure (in this case, Cloudflare Pages). Hugo creates HTML pages and CSS style sheets from the content we write through Markdown or JSON. The HTML pages are then uploaded to Cloudflare Pages, which will serve all user requests.
The link between Hugo (i.e., what we write at a high level) and Cloudflare pages is given by a git repository on which Cloudflare will read to do the website release, i.e., build the website pages.
First you need to install Hugo. As with any Go-based project there are two main options:
download the binary and start it from the folder where you downloaded it: recommended option for those who are beginners and do not want to install Hugo by changing the system path.
download the binary and start it from the PATH: recommended option for those who need to manage multiple Hugo-based projects and want to install it on their machine.
For the first option, it is very simple: just download the binary for your machine’s architecture from the “Releases” section of the project on Github.
For the second option, it all depends on the operating system you are using. Assuming a Unix-based system, you can either use the distribution’s packer manager or download the binary and install it manually within your user’s PATH.
The third, more tricky option is to download the project and manually compile the Hugo binary through Go. Dependency management is not too tricky and is simple enough to install without banging your head against it.
To create a new project, there is no need to import any specific file: Hugo gives us a hand in setting up a new “Hugo” project from scratch. Simply run the command hugo new site my-blog2 to have Hugo create the appropriate folder and file structure for your blog.
Once the structure of our project is created, we can choose the Hugo theme we like best. The official website themes.gohugo.io has a wide range of themes from which we can choose.
Assume in this case that we have chosen the terminal theme. To install it, simply add it as a Git sub-module inside the my-blog folder.
git init
git submodule add https://github.com/panr/hugo-theme-terminal.git themes/terminal
git submodule update --init --recursive
The first very important file to edit is called config.toml and consists of a set of parameters that are used by Hugo and the theme to change certain settings (color of a page, theme used, url base).
Below is a very sparse configuration file. For brevity I have omitted the internal code for configuration, available here.
# (comment) base url is the base address of your blog. In the case of ad-hoc domains (such as nicolo.dev), it should be replaced.
baseurl = "/"
# the language of your site
languageCode = "en"
# the name of the theme you use
theme = "terminal"
paginate = 5
[params]
# this section
# This section contains a set of ad hoc variables used by the Terminal theme.
# Name of the folder where the main content will be (e.g. content/posts).
contentTypeName = "posts"
# ["orange", "blue", "red", "green", "pink"]
themeColor = "orange"
...
Create a new post to give your hugo site initial content. Run the hugo new command in your terminal to generate a new post:
hugo new posts/hello-world.md
Within hello-world.md, add initial content to create your post. Remove the draft line in the frontmatter of the post when you are ready to publish it. Any post with draft: true set will be skipped from the Hugo build process.
Create a new GitHub repository by visiting repo.new. After configuring the repository, push the application to GitHub by running the following commands in the terminal:
git remote add origin https://github.com/yourgithubusername/githubrepo
git branch -M main
git push -u origin main
Deploy the site to Pages by accessing the Cloudflare > Account Home > Pages dashboard and selecting Create a project. Select the newly created GitHub repository and, in the Set up builds and deployments section, provide the following information:
| Option | Value |
|---|---|
| Production branch | main |
| Build command | hugo |
| Build directory | public |
After completing the configuration, click the Save and Deploy button. You should see Cloudflare Pages install hugo and the project dependencies and build your site, before deploying it.
After deploying your site, you will receive a unique subdomain for your project at **.pages.dev. Whenever you commit new code to the Hugo site, Cloudflare Pages automatically rebuilds the project and deploys it. You’ll also have access to preview deployments on new pull requests, so you can preview what the changes to your site will look like before deploying them to production.