GitHub Pages with Hugo: The Complete Guide

GitHub Pages is a fantastic way to host static websites for free. Combined with Hugo, you can quickly create professional websites.

🎯 What You Need

  • A GitHub account
  • Hugo on your local computer
  • Basic knowledge of Git
  • A text editor of your choice

🚀 Step-by-Step Guide

1. Create Hugo Project

# Create new Hugo project
hugo new site my-website
cd my-website

# Initialize Git repository
git init

2. Add Theme

# Add theme as submodule
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# Set theme in configuration
echo 'theme = "PaperMod"' >> hugo.toml

3. GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  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

4. Configure GitHub Repository

  1. Create a new repository on GitHub
  2. Push your code:
git remote add origin https://github.com/USERNAME/REPO-NAME.git
git branch -M main
git add .
git commit -m "Initial commit"
git push -u origin main
  1. Enable GitHub Pages:
    • Go to Settings → Pages
    • Select “GitHub Actions” as Source

⚙️ Optimize Hugo Configuration

Base Configuration

baseURL = 'https://username.github.io/repository-name/'
languageCode = 'en-us'
title = 'My Website'
theme = 'PaperMod'

enableRobotsTXT = true
enableEmoji = true

[params]
  ShowReadingTime = true
  ShowShareButtons = true
  ShowPostNavLinks = true
  ShowBreadCrumbs = true
  ShowCodeCopyButtons = true

[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 10
  [[menu.main]]
    name = "Posts"
    url = "/posts/"
    weight = 20

🎨 Customization and Styling

Add Custom CSS

  1. Create assets/css/custom.css
  2. Add layouts/partials/extend_head.html:
<link rel="stylesheet" href="{{ "css/custom.css" | relURL }}">

📝 Creating Content

New Posts

hugo new content posts/my-post.md

🔧 Advanced Features

Adding Comments

Integrate comment systems such as:

  • Disqus
  • Utterances (GitHub Issues)
  • Giscus (GitHub Discussions)