This guide explains how to deploy a Hugo blog + PaperMod theme + Git submodule + Automated GitHub Actions deployment, suitable for users who want fast, version-controlled blogging with continuous deployment.

1. Preparation

1.1 GitHub Repositories

For this guide, we use GitHub for both 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 : Public repository must already exist before deployment.

1.2 Install Git

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

💡 Tip : Verify Git configuration with git config –list.

1.3 Install Hugo

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

1.4 Generate GitHub Personal Access Token (PAT)

  • Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
  • Enable repo and workflow permissions
  • Copy the token
  • Add as secret in 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. Initialize Hugo Site

2.1 Clone Repository and Initialize Site

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

Directory structure example:

my-blog/
├─ config.toml
├─ content/
├─ themes/
└─ ...

3. PaperMod Theme Module

3.1 Add PaperMod Theme as Submodule

git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule init
git submodule update
  • .gitmodules file will be automatically created:
[submodule "themes/PaperMod"]
    path = themes/PaperMod
    url = https://github.com/adityatelange/hugo-PaperMod.git
  • Enable theme in config.toml:
theme = "PaperMod"
  • Commit submodule:
git add .gitmodules themes/PaperMod
git commit -m "chore: add papermod as a git submodule"
git push origin main

💡 Tip : Submodules allow independent theme updates without affecting main content.

4. Create Post and Local Preview

4.1 Create New Post

hugo new posts/first-post.md

4.2 Preview Locally

hugo server

Open browser: http://localhost:1313/

💡 Tip : Use hugo server -D to include drafts.

5. Public Repository Module (GitHub Pages)

5.1 Setup Public Repository

  • Hugo-generated public/ files will be pushed here
  • Configure GitHub Pages:

6. Automated Deployment Module

6.1 Workflow File

Path: 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@v4
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Build site
        run: hugo --minify

      - 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 Usage

  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 static files and pushes to public repository
  2. Open browser: https://username.github.io

7. Update PaperMod Theme (Optional)

cd themes/PaperMod
git fetch
git checkout main
git pull
cd ../../
git add themes/PaperMod
git commit -m "chore(theme): update papermod theme"
git push origin main

💡 Tip : Next push of blog content will deploy with updated theme automatically.

8. Security and Optimization Tips

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

9. Backup & Rollback

9.1 Backup Important Configurations

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

💡 Tip : Backup GitHub Actions workflow if customized.

9.2 Restore from Backup

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 public repository.

10. Troubleshooting

10.1 Hugo Server Fails to Start

hugo server
  • Check for errors in hugo.yml
  • Ensure themes are properly initialized and submodules updated

10.2 GitHub Actions Fails

  • Verify PAT_TOKEN secret is correct
  • Check workflow logs under Actions tab
  • Ensure public/directory is generated correctly

10.3 Git Submodule Issues

git submodule update --init --recursive

💡 Tip : Always keep submodules up-to-date before deployment.