Build a Blog with Hugo and Deploy it to Cloudflare Pages

In this article, I will guide you step by step through the complete process of building a personal blog using Hugo and deploying it to Cloudflare Pages. Hugo is a fast and flexible static site generator, while Cloudflare Pages offers free static site hosting services with global CDN acceleration, allowing your blog to go live quickly and provide a good user experience. Whether you’re a technical novice or an experienced developer, this tutorial will help you quickly set up your own blog.

Why Choose Hugo and Cloudflare Pages?

• Hugo: Written in Go, it is extremely fast, supports a rich set of themes and Markdown format, making it suitable for blogs and documentation sites.
• Cloudflare Pages: Provides seamless GitHub integration, automatic deployment, free SSL certificates, and global CDN acceleration, offering better access speeds than GitHub Pages in China.
• Cost: The combination of both is completely free, making it ideal for personal blogs or small projects.

Preparation

Before you begin, you need to prepare the following tools and accounts:

1. Hugo: Install the latest version of Hugo (it is recommended to use the extended version for more features).
2. Git: For version control and pushing code to GitHub.
3. GitHub Account: To store the source code of the blog.
4. Cloudflare Account: To deploy and host the blog.
5. Text Editor: Such as VSCode, to edit Markdown files and configuration files.

Step 1: Install Hugo

Windows

1. Install the Chocolatey package manager (if not already installed):
   POWERSHELL

   Collapse Copy

   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

   Click to expand and view more
2. Use Chocolatey to install the extended version of Hugo:
   POWERSHELL

   Collapse Copy

   choco install hugo-extended

   Click to expand and view more
3. Verify the installation:
   POWERSHELL

   Collapse Copy

   hugo version

   Click to expand and view more

macOS

1. Install using Homebrew:
   BASH

   Collapse Copy

   brew install hugo

   Click to expand and view more
2. Verify the installation:
   BASH

   Collapse Copy

   hugo version

   Click to expand and view more

For more installation methods, refer to the Hugo official documentation .

Step 2: Create a Hugo Site

1. Create a new site in the terminal:

   BASH

   Collapse Copy

   hugo new site my-blog
   cd my-blog

   Click to expand and view more

   This will generate the directory structure for the Hugo site in the my-blog folder:

   PLAINTEXT

   Collapse Copy

   ├── archetypes
   ├── content
   ├── data
   ├── layouts
   ├── public
   ├── static
   ├── themes
   └── hugo.toml

   Click to expand and view more

2. Initialize a Git repository:

   BASH

   Collapse Copy

   git init

   Click to expand and view more

3. Add a .gitignore file to ignore generated files:

   BASH

   Collapse Copy

   echo "public/" >> .gitignore
   echo "resources/" >> .gitignore

   Click to expand and view more

Step 3: Install and Configure Theme

1. Choose a Hugo theme, for example, hugo-theme-stack:

   BASH

   Collapse Copy

   git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

   Click to expand and view more

2. Copy the theme’s example configuration file to the project root:

   BASH

   Collapse Copy

   cp themes/hugo-theme-stack/exampleSite/config.yaml .

   Click to expand and view more

3. Edit config.yaml (or hugo.toml) to set basic information:

   YAML

   Collapse Copy

   baseURL: "https://your-domain.com/"  # Replace with your domain
   languageCode: "zh-cn"
   title: "My Blog"
   theme: "hugo-theme-stack"
   DefaultContentLanguage: "zh-cn"
   hasCJKLanguage: true
   paginate: 5

   Click to expand and view more

For more theme configuration, refer to the theme’s official documentation.

Step 4: Create Your First Blog Post

1. Create a new post:

   BASH

   Collapse Copy

   hugo new posts/my-first-post.md

   Click to expand and view more

   This will generate the my-first-post.md file in the content/posts/ directory.

2. Edit the content of the post and modify the Front Matter (post metadata):

   MARKDOWN

   Collapse Copy

   ---
   title: "My First Blog Post"
   date: 2025-06-16T20:29:00+08:00
   draft: false
   ---
   Welcome to the Hugo blog! This is my first post.

   Click to expand and view more

3. Start the Hugo local server to preview:

   BASH

   Collapse Copy

   hugo server -D

   Click to expand and view more

   Open the browser and go to http://localhost:1313/ to see the local preview of the blog.

Step 5: Push Code to GitHub

1. Create a new repository on GitHub (like my-blog), either public or private.
2. Push the local code to GitHub:
   BASH

   Collapse Copy

   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/your-username/my-blog.git
   git branch -M main
   git push -u origin main

   Click to expand and view more

Step 6: Deploy to Cloudflare Pages

1. Log in to the Cloudflare Dashboard, go to “Workers and Pages” > “Pages” > “Create a Project”.

   

2. Connect your GitHub account and select the newly created my-blog repository.

   

3. Configure the build settings:
   • Project Name: Any name (like my-blog), it will assign a subdomain like my-blog.pages.dev.
   • Production Branch: Defaults to main.
   • Build Command: hugo --gc --minify (optimizes output files).
   • Output Directory: public.
   • Environment Variables: Add HUGO_VERSION (like 0.125.4) to specify the Hugo version, it is recommended to use the latest version; check the Hugo Releases.

     

4. Click “Save and Deploy”, Cloudflare Pages will automatically pull the code, build, and deploy it. Once deployment is complete, you can access your blog through my-blog.pages.dev.

   

Step 7: Bind a Custom Domain

1. Ensure your domain is hosted on Cloudflare (you can purchase it through Cloudflare or migrate from other registrars).
2. In the Cloudflare Pages project, click “Custom Domain” > “Set Custom Domain”.
3. Enter your domain (like your-domain.com), Cloudflare will automatically add a CNAME record.
4. Wait for the DNS resolution to take effect (usually a few minutes to a few hours), then access your blog using the custom domain.

Step 8: Automated Deployment

Each time you update your blog content (like adding new posts or modifying configurations), just run the following commands to push the code:

git add .
git commit -m "Update blog content"
git push origin main

Cloudflare Pages will automatically detect updates in the GitHub repository, rebuild and redeploy, typically completing in 1-2 minutes.

Issues and Solutions

1. Mismatch in Hugo Version: Cloudflare Pages might default to an older version of Hugo, causing build failures. The solution is to specify the latest version in the environment variables (like HUGO_VERSION=0.125.4).
2. Posts Not Displaying: Check if the draft: false is set correctly, as Hugo does not render posts with draft: true by default.
3. Slow Access Speed from China: Ensure the domain is accelerated by Cloudflare’s CDN and SSL is enabled.

Summary

With Hugo and Cloudflare Pages, you can quickly build a high-performance, free personal blog. Hugo provides flexible content management and rich theme support, while Cloudflare Pages’ automatic deployment and global CDN acceleration ensure that the blog’s publishing and access are more efficient.

References

• Hugo Official Documentation
• Cloudflare Pages Official Documentation