Deploying to GitHub Pages with Hugo

This guide explains how to deploy your PKB-theme site to GitHub Pages using Hugo’s built-in capabilities.

Prerequisites

• Hugo Extended version installed
• Git repository initialized
• GitHub account
• PKB-theme installed as a submodule

Configuration Steps

1. Update config.toml

   baseURL = "https://username.github.io/repository-name/"
   theme = "PKB-theme"
   publishDir = "docs"  # Required for GitHub Pages
   

2. Create GitHub Workflow Create .github/workflows/hugo.yml:

   name: Deploy Hugo site
   
   on:
     push:
       branches:
         - main
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
           with:
             submodules: true
             fetch-depth: 0
   
         - name: Setup Hugo
           uses: peaceiris/actions-hugo@v2
           with:
             hugo-version: 'latest'
             extended: true
   
         - name: Build
           run: hugo --minify
   
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./public
   

Repository Settings

1. Go to repository Settings → Pages
2. Set Source to:
   • Deploy from a branch
   • Branch: gh-pages (created by the workflow)
   • Folder: / (root)

Local Testing

# Build site
hugo

# Test locally
hugo server

# Deploy changes
git add .
git commit -m "Update site content"
git push origin main

Troubleshooting

Common issues and solutions:

Setting up GitHub Pages with PKB-theme

This guide explains how to set up GitHub Pages for your PKB-theme repository.

Important Files

• _config.yml - Main Jekyll configuration file
• Gemfile - Ruby dependencies for GitHub Pages
• index.md - Your homepage content
• _layouts/ - Theme layout files
• assets/ - Static files like CSS, images, etc.

Setup Steps

1. Configure _config.yml

   • Ensure your _config.yml has the correct theme settings:

   remote_theme: username/PKB-theme
   

2. Enable GitHub Pages