From hugo-repo
This skill should be used when the user asks about deploying Hugo to GitHub Pages, setting up a GitHub Actions workflow for Hugo, Hugo CI/CD pipeline, content-aware path filtering for Hugo builds, caching Hugo modules in CI, Hugo PR preview deployments, Hugo build workflow, or configuring GitHub Pages deployment for a Hugo site. Also applies when troubleshooting GitHub Actions workflow failures related to Hugo builds.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hugo-repo:hugo-github-actionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Deploy Hugo sites to GitHub Pages using GitHub Actions with content-aware path filtering. In repositories where Hugo documentation lives alongside code, path filtering ensures site rebuilds only trigger when content, configuration, or theme files change — not on code-only commits.
Deploy Hugo sites to GitHub Pages using GitHub Actions with content-aware path filtering. In repositories where Hugo documentation lives alongside code, path filtering ensures site rebuilds only trigger when content, configuration, or theme files change — not on code-only commits.
Create .github/workflows/hugo-deploy.yml:
name: Deploy Hugo site to GitHub Pages
on:
push:
branches: [master, main]
paths:
# Hugo content and configuration
- 'content/**'
- 'layouts/**'
- 'static/**'
- 'assets/**'
- 'data/**'
- 'themes/**'
- 'hugo.toml'
- 'hugo.yaml'
- 'hugo.json'
- 'config/**'
- 'go.mod'
- 'go.sum'
# Mounted docs directories (add one per mount)
# - 'plugin-a/docs/**'
# - 'plugin-b/docs/**'
# The workflow file itself
- '.github/workflows/hugo-deploy.yml'
workflow_dispatch: # Allow manual triggering
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
defaults:
run:
shell: bash
jobs:
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: '0.142.0'
HUGO_ENVIRONMENT: production
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: 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 Hugo modules
uses: actions/cache@v4
with:
path: |
~/.cache/hugo_cache
/tmp/hugo_cache
key: ${{ runner.os }}-hugo-${{ hashFiles('go.sum') }}
restore-keys: |
${{ runner.os }}-hugo-
- name: Build with Hugo
run: |
hugo \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- 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
The paths filter is critical for repos where Hugo content lives alongside code. Without it, every code commit triggers a site rebuild.
Add one path entry per mounted docs directory:
on:
push:
paths:
# Standard Hugo directories
- 'content/**'
- 'layouts/**'
- 'static/**'
- 'assets/**'
- 'data/**'
- 'themes/**'
- 'hugo.toml'
- 'go.mod'
- 'go.sum'
# Per-plugin/service docs (one per mount)
- 'plugin-a/docs/**'
- 'plugin-b/docs/**'
- 'services/api/docs/**'
When adding a new mount, also add its path to the workflow filter.
The extended edition is required for SCSS/PostCSS processing. The workflow above uses hugo_extended_ in the download URL. If the theme does not use SCSS, the standard edition works and is smaller:
# Standard edition (no SCSS)
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.deb
Pin the Hugo version in the workflow (HUGO_VERSION: '0.142.0'). Update deliberately, not automatically, since Hugo occasionally has breaking changes in template handling.
Check for updates: https://github.com/gohugoio/hugo/releases
For previewing documentation changes before merging, add a PR workflow that builds but does not deploy:
name: Hugo PR Preview
on:
pull_request:
paths:
- 'content/**'
- 'layouts/**'
- 'data/**'
- 'hugo.toml'
# Add mounted paths
jobs:
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: '0.142.0'
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: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: Build with Hugo
run: hugo --minify --baseURL "https://example.com/"
- name: Report
run: |
echo "## Hugo Build Summary" >> $GITHUB_STEP_SUMMARY
echo "Pages: $(find public -name '*.html' | wc -l)" >> $GITHUB_STEP_SUMMARY
echo "Total size: $(du -sh public | cut -f1)" >> $GITHUB_STEP_SUMMARY
Before the workflow deploys successfully:
| Issue | Fix |
|---|---|
| 404 on deployed site | Check baseURL matches your GitHub Pages URL |
| CSS/JS not loading | Ensure baseURL has trailing slash and uses HTTPS |
| Build succeeds but site empty | Check public/ contains HTML files; verify content is not all draft: true |
| Module resolution fails | Ensure go.mod and go.sum are committed |
| SCSS compilation fails | Use hugo_extended_ in the download URL |
| Old content after deploy | GitHub Pages CDN may cache; wait a few minutes or check cache headers |
npx claudepluginhub therealbill/mynet --plugin hugo-repoSets up Hugo static sites with Tailwind v4, Sveltia/Tina headless CMS, Cloudflare deployment. Fixes theme installs, frontmatter, baseURL, version errors for blogs/docs sites.
Checks and configures GitHub Pages deployment for docs sites, detects generators like MkDocs/TypeDoc/Docusaurus/Sphinx/rustdoc, audits workflows, migrates to actions/deploy-pages.
Generates GitHub Actions workflows for Cloudflare Pages deployment with production, PR preview, and named preview branch support. Includes wrangler config, retry logic, and security best practices.