How I Deployed My Hugo Portfolio Site Using GitHub Pages (The Easy Way)

Hugo is a static site generator built with Go. It’s designed for speed, simplicity, and flexibility. With Hugo, you can create a beautiful website without needing complex frameworks or a backend — everything compiles down to plain HTML, CSS, and JS.

But here’s the kicker: Hugo sites look legit. They don’t have that raw, unfinished vibe that many hand-coded static sites do. Whether you’re building a blog, portfolio, or documentation site — Hugo gives your project a professional, polished look with minimal hassle.

Problems that I ran into 🔧

Now, don’t get me wrong — Hugo is intuitive once you get the hang of it. But at first? It’s a bit overwhelming. Between the directory structure, theme setup, and deployment workflow, I found myself stuck more than once.

So if you’re just getting started and feeling that “Wait, why is it not working?” — relax. You’re not alone. That’s exactly why I wrote this blog: to walk you through it, step by step, and make sure your first Hugo experience is smooth as butter on warm toast.

Getting started with Hugo

I’m using a Linux environment (specifically Ubuntu-based), so here’s how I got Hugo up and running:

There are three ways to set up Hugo

1. Downloading and building the source code itself
2. Downloading via apt
3. Downloading via snap

The first option isn’t beginner-friendly — even I skipped it.

Installing via aptis easy, but the version available there is usually outdated, which can lead to compatibility issues with themes.

So I chose to install it via snap

sudo snap install hugo

then check the version

hugo version

Setting up your website

New folder with name my_portfolio is created, change directory and initialized by git

hugo new site my_portfolio
git init

After installation, let's install a theme there are a lot of themes to choose from which are all listed in Hugo site, but for this project we’ll be using coder theme.

git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder

Configuring hugo.yaml

Here’s a sample config. Replace the placeholder values with your own info.

baseURL = "https://yourdomain.com/"       # Your site's URL (e.g. your custom domain or GitHub Pages URL)
languageCode = "en-us"                    # Language of the website
title = "Your Name"                       # Main title of the site (e.g. your name or blog title)
theme = "hugo-coder"                      # Theme name (must match the folder name in /themes)
defaultContentLanguage = "en"

[pagination]
  pagerSize = 10                             # Number of posts per page

# Site metadata
[params]
  author = "Your Name"                             # Author name displayed on posts
  info = "Software Developer | Writer | Nerd"      # Short tagline
  description = "A personal blog powered by Hugo." # Site description
  keywords = "developer, blog, portfolio, tech"    # SEO keywords
  avatarURL = "images/avatar.png"                  # Profile image (place your image in /static/images/)
  dateFormat = "2006-01-02"                        # Date display format
  since = 2024                                     # Website active since
  colorScheme = "auto"                             # Options: auto, light, dark
  hideCredits = false                              # Set to true to hide theme credits
  hideCopyright = false
  rtl = false                                      # Right-to-left language support
  math = false                                     # Set true if using LaTeX/math rendering
  # options: en, np, fr, etc.
  # You can add multilingual support if needed

# Social Links
[[params.social]]
  name = "GitHub"
  icon = "fa fa-github"                            # Font Awesome class (check what your theme supports)
  weight = 1
  url = "https://github.com/your-username"

[[params.social]]
  name = "LinkedIn"
  icon = "fa fa-linkedin"
  weight = 2
  url = "https://linkedin.com/in/your-username"

[[params.social]]Just feed your CV to ChatGPT and let it draft a clean, structured version.
  name = "Twitter"
  icon = "fa fa-twitter"
  weight = 3
  url = "https://twitter.com/your-handle"

# Syntax highlighting theme for code blocks
[markup]
  [markup.highlight]
    style = "monokai"                              # Choose a style like monokai, dracula, etc.

# Menu Configuration
[[menu.main]]
  name = "Home"
  url = "/"
  weight = 1

[[menu.main]]
  name = "Blog"
  url = "/posts/"
  weight = 2

[[menu.main]]
  name = "Projects"
  url = "/projects/"
  weight = 3

[[menu.main]]
  name = "About"
  url = "/about/"
  weight = 4Just feed your CV to ChatGPT and let it draft a clean, structured version.

Run it Locally

hugo server

Visit http://localhost:1313 to preview your site. You should see your homepage up and running.

“404 Not Found” on Blog/Projects/About?

Hugo doesn’t generate those pages unless you create content inside them. To fix the errors, add these files under the /content/ directory:

content/about.md  
content/posts.md  
content/projects.md

Sample about.md:

---
title: "About"
date: 2024-01-01
---

Hey, I’m a software developer who loves solving real problems with clean code and curious thinking.

I work mostly with Python, Django, and Flask — but I’m always exploring tools that make systems better. Sometimes I write about what I learn to stay sharp and help others do the same.

Outside of code, I’m into Stoicism, sci-fi (especially Star Wars), and observing how tech is reshaping our world.

Let’s build something that matters.

Add your Image

Create a folder imagesinside static and name your image avatar.png

After adding our avatar, we are good to deploy our website in GitHub.

Create a GitHub Repo

Make sure your repo name follows structure.

yourusername.github.io

Enable GitHub Actions

Go to settings>pagesand select source to GitHub Actions.

Build the static site

hugo

This will generate a public/ folder containing your static site. This folder contains index.htmlwhich is very important for deployment.

Deploying to GitHub Pages

Create a file named hugo.yaml in a directory named .github/workflows.

mkdir -p .github/workflows
touch .github/workflows/hugo.yaml

Copy and paste the following hugo.yaml

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    # GitHub-hosted runners automatically enable `set -eo pipefail` for Bash shells.
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      DART_SASS_VERSION: 1.89.2
      HUGO_VERSION: 0.148.0
      HUGO_ENVIRONMENT: production
      TZ: America/Los_Angeles
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Install Dart Sass
        run: |
          wget -O ${{ runner.temp }}/dart-sass.tar.gz https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
          tar -xf ${{ runner.temp }}/dart-sass.tar.gz --directory ${{ runner.temp }}
          mv ${{ runner.temp }}/dart-sass/ /usr/local/bin
          echo "/usr/local/bin/dart-sass" >> $GITHUB_PATH
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Cache Restore
        id: cache-restore
        uses: actions/cache/restore@v4
        with:
          path: |
            ${{ runner.temp }}/hugo_cache
          key: hugo-${{ github.run_id }}
          restore-keys:
            hugo-
      - name: Configure Git
        run: git config core.quotepath false
      - name: Build with Hugo
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            --cacheDir "${{ runner.temp }}/hugo_cache"
      - name: Cache Save
        id: cache-save
        uses: actions/cache/save@v4
        with:
          path: |
            ${{ runner.temp }}/hugo_cache
          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Push the changes

git add .
git commit -m "My portfolio is deployment ready"
git push origin <branch_name>

Once the Build is completed, you’ll see

You can click the Visit site and view your portfolio.

Got questions or stuck somewhere? Drop a comment — I read all of them.😊