This guide shows how to build and deploy a Hugo blog with PaperMod and GitHub Actions for fast, version-controlled publishing with continuous deployment.

1. Preparation

1.1 GitHub Repositories

This guide uses GitHub for both the source and deployment repositories. You need:

  • Private repository: my-blog → for Hugo source files
  • Public repository: username.github.io → for generated static files via GitHub Pages

Tip: The public repository must exist before deployment.

1.2 Git Installation

# Install Git
# Download: https://git-scm.com/
git config --global user.name "yourusername"
git config --global user.email "youremail@example.com"

Tip: Verify the Git configuration with git config --list.

1.3 Hugo Installation

  • Download Hugo (zip package) from Hugo Releases
  • Extract the hugo executable and place it in your system PATH
  • Verify installation:
hugo version

1.4 GitHub Personal Access Token

  • Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
  • Enable repo and workflow permissions
  • Copy the token
  • Add it as a secret in the my-blog repository:
Settings → Secrets → Actions → New repository secret
Name: GH_PAT
Value: <your_token>

Tip: Keep your PAT secure and never expose it publicly.

2. Site Initialization

2.1 Cloning and Initialization

git clone git@github.com:username/my-blog.git
cd my-blog
hugo new site .

Example directory structure:

my-blog/
├─ hugo.yml
├─ content/
├─ themes/
└─ ...

3. PaperMod Setup

3.1 PaperMod Installation

Download a tagged PaperMod release and extract it to themes/PaperMod. Commit the theme files with the site so every checkout uses the same source.

  • Enable the theme in hugo.yml:
theme: PaperMod
  • Commit the theme:
git add themes/PaperMod
git commit -m "chore: add PaperMod theme"
git push origin main

Tip: Use a tagged PaperMod release so theme updates are intentional and reproducible.

4. Post Creation and Preview

4.1 Post Creation

hugo new posts/first-post.md

4.2 Local Preview

hugo server

Open http://localhost:1313/ in your browser.

Tip: Use hugo server -D to include drafts.

5. GitHub Pages Repository

5.1 Public Repository Configuration

  • The generated public/ files will be pushed to this repository.
  • Configure GitHub Pages:

6. Automated Deployment

6.1 Workflow File

Create the workflow at my-blog/.github/workflows/deploy.yml:

name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v5

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.166.0"
          extended: true

      - name: Build site
        run: hugo --gc --minify --panicOnWarning

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.GH_PAT }}
          publish_dir: ./public
          external_repository: username/username.github.io
          publish_branch: main

6.2 Site Publishing

  1. Make changes locally:
git add .
git commit -m "feat(blog): add new post 'how to set up hugo blog'"
git push origin main
  1. GitHub Actions automatically builds the static files and pushes them to the public repository.
  2. Open https://username.github.io in your browser.

7. PaperMod Updates (Optional)

Replace themes/PaperMod with a newer tagged release, run the strict local build, and review the changes before committing them.

Tip: Update Hugo and PaperMod separately so failures are easier to identify.

8. Security

  1. Keep your GitHub PAT secure.
  2. Regularly update Hugo and the PaperMod theme.
  3. Use descriptive commit messages for better tracking.
  4. Test locally before deploying to GitHub Pages.

9. Backup and Restore

9.1 Configuration Backup

sudo mkdir -p /root/backup/hugo
sudo cp -r hugo.yml content themes /root/backup/hugo/

Tip: Back up the GitHub Actions workflow if you customize it.

9.2 Configuration Restore

sudo cp -r /root/backup/hugo/* .
git add .
git commit -m "chore: restore from backup"
git push origin main

Tip: Always test locally before pushing to the public repository.

10. Troubleshooting

10.1 Hugo Server Startup Errors

hugo server
  • Check for errors in hugo.yml
  • Ensure themes/PaperMod exists and matches a supported release

10.2 GitHub Actions Workflow Errors

  • Verify the GH_PAT secret is correct
  • Check the workflow logs in the Actions tab
  • Ensure the public/ directory is generated correctly

10.3 Theme Issues

  • Confirm theme: PaperMod is present in hugo.yml.
  • Confirm the complete PaperMod release exists in themes/PaperMod.
  • Run the strict local build and resolve every warning before deployment.