If you want a personal site or portfolio and don't want to pay for hosting or deal with a CMS, Hugo + GitHub Pages is the cleanest option out there. Your site builds in milliseconds, lives in a git repo, and deploys for free.

This guide walks through the whole thing from scratch.

What You Need

Before starting, make sure you have:

• Hugo installed — gohugo.io/installation
• A GitHub account
• Git installed

Install Hugo:

# macOS
brew install hugo
Windows
choco install hugo-extended
Linux
sudo snap install hugo

Verify it's working:

hugo version

💡 Make sure you install the extended version — many themes require it for SCSS compilation.

Step 1 — Create a New Site

hugo new site my-site
cd my-site
git init

This generates the Hugo scaffolding — content/, layouts/, static/, and hugo.toml.

Step 2 — Add a Theme

Hugo ships with no default theme, so you need to add one. Browse themes.gohugo.io and pick one. We'll use PaperMod here — clean, fast, and well-maintained.

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

Then open hugo.toml and tell Hugo to use it:

theme = "PaperMod"

⚠️ Always add themes as git submodules, not by copying files. This keeps the theme updateable and plays nicely with GitHub Actions.

Step 3 — Configure the Site

Open hugo.toml and fill in your details:

baseURL = "https://your-username.github.io/"
languageCode = "en-us"
title = "Your Name"
theme = "PaperMod"
[params]
description = “Your site description”

💡 The baseURL must match your GitHub Pages URL exactly — including the trailing slash. Get this wrong and your CSS, images, and links will all break.

Step 4 — Add Your First Post

hugo new content posts/hello-world.md

Open the generated file at content/posts/hello-world.md. It will look like:

---
title: Hello World
date: 2026-04-29
draft: true
---

Set draft: false and write your content below the second ---.

Preview the site locally:

hugo server -D

Visit http://localhost:1313 — you should see your post live with hot reload on every save.

Step 5 — Create a GitHub Repository

Go to GitHub and create a new repository named exactly:

your-username.github.io

This naming convention is what makes GitHub serve it at the root URL. For example, if your username is chris, the repo is chris.github.io and the site lives at https://chris.github.io.

Push your local site to it:

git add .
git commit -m "initial site"
git branch -M main
git remote add origin https://github.com/your-username/your-username.github.io.git
git push -u origin main

Step 6 — Set Up Automated Deployment

Instead of manually running hugo and copying files, we'll use GitHub Actions to build and deploy on every push.

Create the file .github/workflows/deploy.yml:

name: Deploy Hugo Site
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
submodules: recursive        # needed to pull the theme
  - name: Setup Hugo
    uses: peaceiris/actions-hugo@v3
    with:
      hugo-version: latest
      extended: true

  - name: Build
    run: hugo --minify

  - name: Upload artifact
    uses: actions/upload-pages-artifact@v3
    with:
      path: ./public
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
uses: actions/deploy-pages@v4

Commit and push this file:

git add .github/workflows/deploy.yml
git commit -m "add deploy workflow"
git push

Step 7 — Enable GitHub Pages

In your repository:

1. Go to Settings → Pages
2. Under Source, select GitHub Actions
3. Save

That's it. GitHub will now run the workflow on every push to main. Check the Actions tab to watch the build — it takes about 30–60 seconds.

Your site will be live at:

https://your-username.github.io

What's Next

Once your site is running, a few things worth doing:

• Add more posts — create files under content/posts/ and push
• Customise the theme — most themes expose config options in hugo.toml, check the theme's README
• Custom domain — buy a domain, add a CNAME file to your static/ folder, and configure DNS to point at your-username.github.io
• Analytics — drop in a script tag via layouts/partials/ without touching the theme files

Why Hugo Over Other Options

Hugo wins on build speed and simplicity for content-first sites. If you need interactivity or server-side logic, reach for Next.js instead.

The whole setup takes under 30 minutes and costs nothing. Once it's running, publishing is just writing a markdown file and running git push.