Follow this guide to build a high-performance web service that’s completely free to run forever. We’ll use Hugo (static site generator), GitHub (version control), and Cloudflare Pages (free hosting).

Table of Contents

1. Why Free Web Hosting is Possible
2. Tech Stack Overview
3. Prerequisites
4. Installing Hugo
5. Creating a Project
6. Installing a Theme
7. Configuration File Setup
8. Creating Your First Content
9. Testing Locally
10. Uploading to GitHub
11. Deploying with Cloudflare Pages
12. Conclusion
13. References

Why Free Web Hosting is Possible

Do you think running a web service requires server costs?

With Hugo + GitHub + Cloudflare Pages:

• $0 Server Costs: Static sites don’t need a server
• Free Hosting: Cloudflare Pages free plan offers unlimited bandwidth
• Auto Deploy: Just git push and it updates automatically
• Global CDN: Fast speeds from anywhere in the world
• Free SSL: HTTPS is automatically enabled

Comparison with Other Platforms

Why Choose Hugo

1. Complete Ownership: Your content, your data, your domain. Platform shutdown doesn’t affect you.

2. Developer Branding: A tech blog on your GitHub profile serves as a portfolio.

3. Real Skills: Naturally learn Git, CI/CD, Markdown and other industry skills.

4. Multilingual Support: Easy to build multilingual sites for global audiences.

This guide is based on Hugo’s Official Quick Start and Cloudflare Pages Documentation.

Tech Stack Overview

Let’s briefly look at the three core technologies.

Free deployment pipeline combining Hugo, GitHub, and Cloudflare

Hugo: Static Site Generator

Markdown files are converted to HTML through the Hugo engine

Hugo is the world’s fastest static site generator, written in Go.

Hugo Official Site

GitHub: Version Control & Storage

Git tracks code change history, and GitHub stores it safely in the cloud.

• Restore to any previous version if something goes wrong
• Work across multiple devices with sync
• Connect to Cloudflare for automatic deployment

GitHub Official Site

Cloudflare Pages: Free Hosting & Auto Deploy

Push to GitHub and Cloudflare automatically builds and deploys

Cloudflare Pages connects to your GitHub repository to automatically build and deploy worldwide.

Cloudflare Pages Documentation

Prerequisites

Installing Hugo

macOS (Using Homebrew)

Open Terminal and run these commands in order.

1. Install Homebrew if you don’t have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Homebrew Official Site

2. Install Hugo:

brew install hugo

3. Verify installation:

hugo version

You should see output similar to:

hugo v0.154.3+extended+withdeploy darwin/arm64 ...

Windows

Windows users, please refer to the official installation guide.

Creating a Project

# Create new Hugo site (in blog folder)
hugo new site blog

# Move to created folder
cd blog

Project Structure

Basic folder structure of a Hugo project

Installing a Theme

Browse Hugo Themes to find one you like. Hundreds of free themes are available.

Recommended Themes

This site uses the Stack theme. It’s great for placing ad widgets in the sidebar and has well-organized archives/tags.

Why Use Git Submodule

Important: Always install themes using Git Submodule.

As recommended in Hugo’s official documentation:

• Separates theme code from your project code
• Easy updates with git submodule update
• Required for Cloudflare Pages deployment (regular copy causes errors)

Installation Commands

Stack theme (used on this site):

# Initialize Git repository
git init

# Add Stack theme as submodule
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

Stack Official Documentation

Configuration File Setup

Open hugo.toml and replace with the following content. Comments explain each setting.

# ============================================
# Basic Settings
# ============================================
baseURL = 'https://yourdomain.pages.dev/'  # Change to actual URL after deployment
title = 'My Tech Blog'                      # Site title
theme = 'hugo-theme-stack'                  # Theme to use

# ============================================
# Language Settings
# ============================================
defaultContentLanguage = 'en'              # Default language: English
defaultContentLanguageInSubdir = true      # Use /en/, /ko/ prefixes in URL
enableRobotsTXT = true                     # Auto-generate robots.txt

# ============================================
# Search Feature (hugo-theme-stack built-in)
# ============================================
[outputs]
  home = ["HTML", "RSS", "JSON"]           # JSON required for search

# ============================================
# Language-specific Settings
# ============================================
[languages]
  # --- English ---
  [languages.en]
    languageCode = 'en-US'
    languageName = 'English'
    weight = 1
    
    [languages.en.params]
      description = 'Developer Tech Blog'
      mainSections = ["posts"]

    [[languages.en.menu.main]]
      name = "Archive"
      url = "/archives/"
      weight = 10
    [[languages.en.menu.main]]
      name = "Tags"
      url = "/tags/"
      weight = 20
    [[languages.en.menu.main]]
      name = "Search"
      url = "/search/"
      weight = 30

  # --- Korean ---
  [languages.ko]
    languageCode = 'ko-KR'
    languageName = '한국어'
    weight = 2
    
    [languages.ko.params]
      description = '개발자의 기술 블로그'
      mainSections = ["posts"]

    [[languages.ko.menu.main]]
      name = "Archive"
      url = "/archives/"
      weight = 10
    [[languages.ko.menu.main]]
      name = "Tags"
      url = "/tags/"
      weight = 20
    [[languages.ko.menu.main]]
      name = "Search"
      url = "/search/"
      weight = 30

# ============================================
# Stack Theme Settings
# ============================================
[params]
  # Site basic info
  description = 'Developer Tech Blog'
  mainSections = ['posts']
  
  # Sidebar settings
  [params.sidebar]
    emoji = ''
    subtitle = 'Dev Blog'
    
    [params.sidebar.avatar]
      enabled = true
      local = true
      src = 'images/avatar.png'

  # Comments (enable later)
  [params.comments]
    enabled = false

  # Footer settings
  [params.footer]
    since = 2026

  # Color settings
  [params.colorScheme]
    toggle = true
    default = 'auto'

Creating Your First Content

Creating Required Pages

Stack theme needs a few pages to work properly:

# Archive page (post list)
cat > content/archives.md << 'EOF'
---
title: "Archive"
layout: "archives"
summary: "archives"
---
EOF

# Search page
cat > content/search.md << 'EOF'
---
title: "Search"
layout: "search"
summary: "search"
---
EOF

Writing Your First Post

Using Leaf Bundle style (folder + index.md) makes image management easier:

# Create new post folder
hugo new content/posts/hello-world/index.md

Open the created content/posts/hello-world/index.md and write your content:

+++
date = '2026-01-08T10:00:00+09:00'
draft = false
title = 'Hello, this is my first post!'
tags = ["first", "Hugo"]
+++

## Introduction

This site was built with Hugo and Cloudflare Pages.

## Future Plans

- Share development experiences
- Write technical tutorials

Testing Locally

Let’s test locally before deploying:

hugo server -D

Visit http://localhost:1313 in your browser!

The -D option shows posts with draft = true.

Uploading to GitHub

1. Create a New Repository on GitHub

1. Log in to GitHub
2. Click + button in top right → New repository
3. Repository name: my-blog (or your preferred name)
4. Choose Public or Private
5. Click Create repository

2. Connect Local Project

# Create .gitignore (exclude build output)
echo "public/" >> .gitignore
echo "resources/" >> .gitignore
echo ".hugo_build.lock" >> .gitignore

# Connect to GitHub repository
git remote add origin https://github.com/username/my-blog.git

# First commit & push
git add .
git commit -m "Initial commit: Hugo blog setup"
git branch -M main
git push -u origin main

Deploying with Cloudflare Pages

1. Access Cloudflare Dashboard

Log in to https://dash.cloudflare.com.

2. Create New Pages Project

Step 1: Click the + button in top right and select Pages.

Select Pages from Cloudflare dashboard

Step 2: On the “Get started” screen, click Get started under Import an existing Git repository.

Select import Git repository option

Step 3: Connect your GitHub account and select the my-blog repository you just created.

First-time connection will show GitHub permission dialog. Click Authorize Cloudflare.

3. Build Settings

Important: In Environment Variables, set HUGO_VERSION to 0.154.3 (or your local version).

4. Start Deployment

Click Save and Deploy and the build will start automatically.

After a few minutes, you can access your site at https://projectname.pages.dev.

Conclusion

You now have a completely free environment:

Next Steps

• Connect custom domain (e.g., myblog.com)
• Add comment system (Giscus, Utterances)
• SEO optimization

References

Official Documentation

• Hugo Official Site
• Hugo Quick Start
• Stack Theme Documentation
• Cloudflare Pages Documentation

Additional Learning

• Markdown Syntax Guide
• Git Basics
• Hugo Theme Gallery

Questions or feedback? Leave a comment below!