Hugo

Hugo Static Site Generator Skill

Status: Production Ready ✅ Last Updated: 2025-11-04 Production Tested: https://hugo-blog-test.webfonts.workers.dev

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• hugo
• hugo extended
• static site generator
• ssg
• hugo blog
• hugo documentation
• hugo site

Secondary Keywords

• papermod
• hugo themes
• go templates
• sveltia cms
• cloudflare pages
• workers static assets
• hugo server
• hugo build
• hugo new site
• content management
• static website
• jamstack
• markdown blog
• docs site
• hugo modules
• git submodules
• frontmatter
• yaml config
• toml config

Error-Based Keywords

• "SCSS support not enabled"
• "theme not found"
• "hugo version mismatch"
• "baseurl error"
• "broken asset links"
• "css not loading"
• "theme missing"
• "frontmatter parse error"
• "hugo extended required"
• "git submodule not found"

---

What This Skill Does

This skill provides comprehensive Hugo static site generator knowledge, covering project scaffolding, theme integration, Sveltia CMS setup, and Cloudflare Workers deployment. It prevents 9 documented errors and provides 4 production-ready templates (blog, docs, landing page, minimal starter).

Core Capabilities

✅ Hugo Extended Installation - Correct version selection, all platforms ✅ Project Scaffolding - YAML config, directory structure, best practices ✅ Theme Integration - PaperMod, Hugo Book, custom themes via Git submodules ✅ Sveltia CMS Setup - Primary CMS recommendation with full configuration ✅ Cloudflare Workers Deployment - wrangler.jsonc config, GitHub Actions CI/CD ✅ Error Prevention - All 9 common Hugo errors documented and solved ✅ 4 Ready-to-Use Templates - Blog, docs, landing page, minimal starter ✅ TinaCMS Alternative - Documented but not recommended (Sveltia preferred)

---

Known Issues This Skill Prevents

Issue	Why It Happens	Source	How Skill Fixes It
SCSS support not enabled	Hugo Standard installed instead of Extended	Hugo FAQ	Always installs Hugo Extended, verifies with hugo version
Broken asset links	baseURL mismatch between config and deployment	Hugo/Cloudflare docs	Environment-specific configs or -b flag usage
TOML/YAML confusion	Mixing formats or using TOML with Sveltia	Sveltia docs	Enforces YAML config (--format yaml flag)
Theme not found	Missing Git submodules or wrong config	Hugo themes docs	Proper submodule setup, submodules: recursive in CI/CD
Version mismatch	Different Hugo versions local vs CI/CD	GitHub Actions docs	Pins Hugo version in workflows
Future-dated posts	Posts invisible due to future dates	Hugo date handling	Documents --buildFuture flag and date validation
Public/ folder conflicts	Committing build output to Git	Hugo best practices	.gitignore configuration
Frontmatter errors	Wrong delimiters or invalid syntax	Hugo content docs	YAML format validation, correct delimiters
Module cache issues	Corrupted Hugo Modules cache	Hugo modules docs, GitHub	hugo mod clean solution, Git submodules preferred

---

When to Use This Skill

✅ Use When:

• Building blogs, documentation sites, landing pages, or portfolios
• Setting up Hugo for the first time
• Integrating Sveltia CMS or TinaCMS
• Deploying to Cloudflare Workers with Static Assets
• Installing themes (PaperMod, Hugo Book, etc.)
• Encountering Hugo build or deployment errors
• Need fast static site generation (<100ms builds)
• Setting up GitHub Actions CI/CD for Hugo
• Choosing between Hugo Extended and Standard
• Configuring baseURL for deployment

❌ Don't Use When:

• Need React/Vue/Svelte components (use Next.js or Astro instead)
• Require real-time database features (use full-stack framework)
• Building complex interactive web apps (Hugo is for static content)
• Need server-side rendering (Hugo is static only)

---

Quick Usage Example

# 1. Install Hugo Extended
brew install hugo
# OR
wget https://github.com/gohugoio/hugo/releases/download/v0.152.2/hugo_extended_0.152.2_linux-amd64.deb
sudo dpkg -i hugo_extended_0.152.2_linux-amd64.deb

# 2. Create new site with YAML config
hugo new site my-blog --format yaml
cd my-blog
git init

# 3. Add PaperMod theme
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# 4. Configure hugo.yaml
echo 'theme: "PaperMod"' >> hugo.yaml

# 5. Create first post
hugo new content posts/first-post.md

# 6. Build and deploy
hugo --minify
npx wrangler deploy

Result: Working Hugo blog with PaperMod theme deployed to Cloudflare Workers in ~5 minutes

Full instructions: See SKILL.md

---

Package Versions (Verified 2025-11-04)

Package	Version	Status
Hugo Extended	v0.152.2	✅ Latest stable (Oct 24, 2025)
PaperMod Theme	Latest	✅ Via Git submodule
Sveltia CMS	Latest	✅ Via CDN (unpkg)
Wrangler	v4.37.1+	✅ Compatible (v4.45.3 available)

---

Dependencies

Prerequisites: None (Hugo is standalone binary)

Integrates With:

• sveltia-cms skill (recommended CMS companion)
• cloudflare-worker-base skill (deployment patterns)
• tailwind-v4-shadcn skill (styling Hugo sites)
• tinacms skill (alternative CMS, not recommended)

---

File Structure

hugo/
├── SKILL.md              # Complete Hugo documentation
├── README.md             # This file
├── scripts/              # Automation scripts
│   ├── init-hugo.sh          # Automated project setup
│   ├── deploy-workers.sh     # Manual deployment script
│   └── check-versions.sh     # Version verification
├── templates/            # 4 complete Hugo templates
│   ├── hugo-blog/            # PaperMod blog template
│   ├── hugo-docs/            # Documentation site template
│   ├── hugo-landing/         # Landing page template
│   └── minimal-starter/      # Bare-bones starter
├── references/           # Detailed guides
│   ├── sveltia-integration-guide.md
│   ├── workers-deployment-guide.md
│   ├── common-errors.md
│   ├── theme-customization-guide.md
│   └── hugo-vs-alternatives.md
└── assets/               # Screenshots and diagrams
    ├── screenshots/
    └── diagrams/

---

Official Documentation

• Hugo: https://gohugo.io/documentation/
• PaperMod Theme: https://github.com/adityatelange/hugo-PaperMod/wiki
• Sveltia CMS: https://github.com/sveltia/sveltia-cms
• Cloudflare Workers: https://developers.cloudflare.com/workers/
• Hugo Themes: https://themes.gohugo.io/
• Context7 Library: /gohugoio/hugo (for API reference)

---

Related Skills

• sveltia-cms - Headless CMS for Hugo (strongly recommended)
• cloudflare-worker-base - Workers deployment patterns
• cloudflare-d1 - Database integration (if needed)
• tailwind-v4-shadcn - Styling Hugo sites with Tailwind v4
• tinacms - Alternative CMS (not recommended for Hugo)
• project-planning - Use for planning large Hugo projects

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/secondsky/claude-skills/issues
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: https://hugo-blog-test.webfonts.workers.dev Build Time: 24ms (20 pages) Deployment: ~21 seconds Token Savings: ~60-65% Error Prevention: 100% (9/9 errors prevented) Ready to use! See SKILL.md for complete setup.