Introduction

Want to start a blog but worried about hosting and domain costs? The combination of GitHub Pages and Hugo offers the perfect solution. GitHub Pages provides free web hosting, while Hugo is a blazing-fast static site generator. Together, they let you run a professional-quality blog at zero cost.

This guide walks through the entire setup process, from installing Hugo to deploying your site on GitHub Pages.

What is Hugo?

Hugo is a static site generator written in Go. You write content in Markdown, and Hugo generates HTML files with a single command. Unlike WordPress, no database is required—just upload the generated HTML files and your site is live.

Key features of Hugo:

• Fast builds: Sites with hundreds of pages are generated in seconds
• Rich theme ecosystem: Over 300 themes available on the official site
• Built-in i18n: Easily build multi-language sites (e.g., Japanese + English)
• Highly customizable: Simple yet powerful template language

What is GitHub Pages?

GitHub Pages is a free web hosting service provided by GitHub. Push HTML files to a repository, and they are automatically published as a website. It supports custom domains and provides free HTTPS certificates.

Setup Steps

1. Install Hugo

Install Hugo on your local machine.

macOS:

brew install hugo

Windows:

winget install Hugo.Hugo

Verify:

hugo version

2. Create a New Site

hugo new site my-blog
cd my-blog

3. Add a Theme

Choose a theme and add it. Here is an example using the popular PaperMod theme.

git init
git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

Enable the theme by adding to hugo.toml:

theme = "PaperMod"

4. Create Your First Post

hugo new content posts/first-post.md

Front matter is automatically inserted. Change draft: true to draft: false to publish.

5. Preview Locally

hugo server -D

Open http://localhost:1313 in your browser to see your site.

Deploy to GitHub Pages

1. Create a GitHub Repository

Create a new repository on GitHub. Naming it <username>.github.io makes it accessible directly at that URL.

2. Set Up Deployment Workflow

Create .github/workflows/hugo.yaml with the following content to enable automatic deployment via GitHub Actions.

name: Deploy Hugo site to Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-hugo@v3
      - run: hugo --minify
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

3. Push and Publish

git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/repository.git
git push -u origin main

After pushing, GitHub Actions automatically builds and deploys your site. Within minutes, it will be live at https://username.github.io/repository/.

Custom Domain Setup (Optional)

If you have a custom domain, configure it in GitHub Pages.

1. Go to repository Settings → Pages → Custom domain
2. Add the following A records to your DNS:
   • 185.199.108.153
   • 185.199.109.153
   • 185.199.110.153
   • 185.199.111.153
3. Or set a CNAME record pointing to <username>.github.io

GitHub automatically issues and manages HTTPS certificates.

Conclusion

The GitHub Pages and Hugo combination is one of the best ways to run a full-featured blog at zero cost. With no server maintenance required and Markdown-based writing, you can focus entirely on creating content. Why not start your own blog today?