Hugo Static Site Generator

Status: Production Ready | Last Updated: 2025-11-21 Latest Version: hugo@0.152.2+extended | Build Speed: <100ms

Quick Start (5 Minutes)

1. Install Hugo Extended

CRITICAL: Always install Hugo Extended edition (not Standard) unless you're certain you don't need SCSS/Sass support. Most themes require Extended.

# macOS
brew install hugo

# Linux (Ubuntu/Debian)
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

# Verify Extended edition
hugo version  # Should show "+extended"

Why this matters:

• Hugo Extended includes SCSS/Sass processing
• Most popular themes (PaperMod, Academic, Docsy) require Extended
• Standard edition will fail with "SCSS support not enabled" errors
• Extended has no downsides (same speed, same features + more)

2. Create New Hugo Site

# Use YAML format (not TOML) for better CMS compatibility
hugo new site my-blog --format yaml

# Initialize Git
cd my-blog
git init

# Add PaperMod theme (recommended for blogs)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

CRITICAL:

• Use

  --format yaml

  to create hugo.yaml (not hugo.toml)
• YAML is required for Sveltia CMS and recommended for TinaCMS
• TOML has known bugs in Sveltia CMS beta
• Git submodules require

  --recursive

  flag when cloning later

3. Configure and Build

# hugo.yaml - Minimal working configuration
baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
enableRobotsTXT: true

params:
  ShowReadingTime: true
  ShowShareButtons: true
  defaultTheme: auto  # Supports dark/light/auto

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

# Run development server (with live reload)
hugo server

# Build for production
hugo --minify

# Output is in public/ directory

Critical Rules

Always Do

✅ Install Hugo Extended (not Standard) - required for SCSS/Sass support in themes ✅ Use YAML configuration (

--format yaml

public/

draft: false

--recursive

/images/photo.jpg

../images/photo.jpg

hugo --minify

Never Do

❌ Don't install Hugo Standard - most themes require Extended edition ❌ Don't use TOML config with Sveltia CMS - has known bugs, use YAML instead ❌ Don't commit

public/

submodules: recursive

-b $CF_PAGES_URL

resources/_gen/

.hugo_build.lock

Top 5 Errors Prevention

This skill prevents 15 documented errors. Here are the top 5:

Error #1: Version Mismatch (Hugo vs Hugo Extended)

Error:

Error: SCSS support not enabled

hugo version | grep extended

references/error-catalog.md

Error #2: baseURL Configuration Errors

Error: Broken CSS/JS/image links, 404s on all assets Prevention: Use environment-specific configs or build flag:

hugo -b $CF_PAGES_URL

references/error-catalog.md

Error #3: Theme Not Found Errors

Error:

Error: module "PaperMod" not found

theme: "PaperMod"

git submodule update --init --recursive

references/error-catalog.md

Error #4: Hugo Version Mismatch (Local vs Deployment)

Error: Features work locally but fail in CI/CD, or vice versa Prevention: Pin Hugo version everywhere (CI/CD, local docs, package.json if using npm) See:

references/error-catalog.md

Error #5: Git Submodule Not Found in CI/CD

Error: Theme works locally but not in CI/CD, blank site on deployment Prevention: Add

submodules: recursive

references/error-catalog.md

For complete error catalog (all 15 errors): See

references/error-catalog.md

Using Bundled Resources

References (

references/

• setup-guide.md

  - Complete Hugo setup walkthrough (installation, themes, deployment)

• error-catalog.md

  - All 15 common Hugo errors with solutions and prevention

• common-patterns.md

  - Best practices and patterns (taxonomies, content organization, multilingual)

• cms-integration.md

  - Sveltia CMS integration guide with configuration

• tailwind-integration.md

  - Tailwind CSS integration with Hugo Pipes

• advanced-topics.md

  - Advanced Hugo features (modules, data files, internationalization)

Templates (templates/)

Complete, production-ready Hugo projects ready to copy:

• templates/hugo-blog/

  - Blog with PaperMod theme
  • Dark/light mode, search, tags, archives
  • Sveltia CMS pre-configured
  • wrangler.jsonc for Workers deployment
  • GitHub Actions workflow included
  • Use when: Building a personal blog, company blog, or news site

• templates/hugo-docs/

  - Documentation site with Hugo Book theme
  • Nested navigation, search, breadcrumbs
  • Sveltia CMS for docs editing
  • Use when: Creating technical documentation, knowledge bases, API docs

• templates/hugo-landing/

  - Landing page with custom layouts
  • Hero, features, testimonials, CTA sections
  • No theme dependency (custom layouts)
  • Optimized for conversions
  • Use when: Building marketing sites, product pages, portfolios

• templates/minimal-starter/

  - Bare-bones starter
  • No theme, clean slate
  • Setup guide for adding themes
  • Minimal configuration
  • Use when: Starting from scratch with full control

Quick start with template:

cp -r templates/hugo-blog/ my-new-blog/
cd my-new-blog
git submodule update --init --recursive
hugo server

References (references/)

Detailed guides loaded when needed:

• references/setup-guide.md

  - Complete 7-step setup process
  • Installation and verification
  • Project scaffolding
  • Theme installation
  • Configuration options
  • Content creation
  • Build and development
  • Cloudflare Workers deployment
  • Load when: Setting up new Hugo project from scratch

• references/cms-integration.md

  - Headless CMS integration
  • Sveltia CMS setup (recommended) - 5 minutes
  • OAuth configuration for production
  • TinaCMS setup (not recommended)
  • Comparison and troubleshooting
  • Load when: Adding content management to Hugo site

• references/tailwind-integration.md

  - Tailwind CSS v4 integration
  • Hugo Pipes + PostCSS setup
  • Dark mode implementation (CSS-only and Alpine.js)
  • Typography and Forms plugins
  • Production optimization
  • Common issues and solutions
  • Load when: Integrating Tailwind CSS with Hugo

• references/common-patterns.md

  - 7 common project patterns
  • Blog with PaperMod
  • Documentation with Hugo Book
  • Landing pages
  • Multilingual sites
  • Portfolio sites
  • E-commerce (static)
  • Newsletter/blog
  • Load when: Choosing architecture for specific use case

• references/advanced-topics.md

  - Advanced Hugo features
  • Custom shortcodes
  • Image processing
  • Custom taxonomies
  • Data files (JSON/YAML/CSV)
  • Page bundles
  • Template overrides
  • Hugo Modules
  • Load when: User needs advanced customization

• references/error-catalog.md

  - All 15 documented errors
  • Complete error messages and solutions
  • Prevention strategies
  • Official sources cited
  • Troubleshooting guide
  • Load when: Debugging issues or preventing known errors

Common Use Cases

Use Case 1: Personal Blog

Template:

templates/hugo-blog/

cp -r templates/hugo-blog/ my-blog/
cd my-blog
git submodule update --init --recursive
hugo new content posts/first-post.md
hugo server

See

references/common-patterns.md

Use Case 2: Technical Documentation

Template:

templates/hugo-docs/

cp -r templates/hugo-docs/ docs-site/
cd docs-site
git submodule update --init --recursive
hugo new content docs/getting-started/installation.md
hugo server

See

references/common-patterns.md

Use Case 3: Landing Page

Template:

templates/hugo-landing/

cp -r templates/hugo-landing/ landing/
cd landing
hugo server

See

references/common-patterns.md

Use Case 4: Blog with Tailwind CSS v4

Template: Start with

templates/minimal-starter/

references/tailwind-integration.md

cp -r templates/minimal-starter/ tailwind-blog/
cd tailwind-blog
# Follow references/tailwind-integration.md for setup

See

references/tailwind-integration.md

Use Case 5: Multilingual Documentation

Template:

templates/hugo-docs/

See

references/common-patterns.md

Cloudflare Workers Deployment

Quick Deployment

1. Create wrangler.jsonc:

{
  "name": "my-hugo-site",
  "compatibility_date": "2025-01-29",
  "assets": {
    "directory": "./public",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page"
  }
}

2. Deploy:

hugo --minify
bunx wrangler deploy

For complete deployment guide: See

references/setup-guide.md

When to Load Detailed References

Load

references/setup-guide.md

• User needs complete 7-step setup process
• User asks about configuration options
• User needs detailed installation instructions
• User asks about directory structure
• User needs GitHub Actions workflow

Load

references/cms-integration.md

• User wants to add CMS to Hugo site
• User asks about Sveltia CMS setup
• User asks about TinaCMS (warn it's not recommended)
• User needs OAuth configuration
• User asks about content management

Load

references/tailwind-integration.md

• User wants to integrate Tailwind CSS v4
• User asks about PostCSS setup
• User needs dark mode implementation
• User asks about Tailwind plugins
• User has CSS processing errors

Load

references/common-patterns.md

• User asks "how do I build a [blog/docs/landing page]?"
• User needs architecture guidance
• User asks about multilingual sites
• User asks about portfolio sites
• User needs project structure examples

Load

references/advanced-topics.md

• User asks about shortcodes
• User needs image processing
• User wants custom taxonomies
• User asks about data files
• User needs template customization

Load

references/error-catalog.md

• User encounters an error
• User asks about troubleshooting
• User wants to prevent known issues
• User asks "what errors should I watch out for?"
• User has deployment issues

Dependencies

Required:

• Hugo v0.149.0+ (Extended edition) - Static site generator

Optional (for deployment):

• wrangler v4.0.0+ - Cloudflare Workers deployment
• Git v2.0+ - Version control and theme submodules

Optional (for CMS):

• Sveltia CMS (latest) - Content management (CDN-based, no installation)

Official Documentation

• Hugo: https://gohugo.io/documentation/
• PaperMod Theme: https://github.com/adityatelange/hugo-PaperMod/wiki
• Hugo Book Theme: https://github.com/alex-shpak/hugo-book
• Sveltia CMS: https://github.com/sveltia/sveltia-cms
• Cloudflare Workers: https://developers.cloudflare.com/workers/
• Hugo Themes: https://themes.gohugo.io/

Package Versions (Verified 2025-11-04)

Hugo: v0.152.2+extended (October 24, 2025) PaperMod: Latest (via Git submodule) Sveltia CMS: Latest (via CDN) Wrangler: v4.37.1+ (v4.45.3 available)

Production Example

This skill is based on live testing:

• Test Site: https://hugo-blog-test.webfonts.workers.dev
• Build Time: 24ms (20 pages)
• Deployment Time: ~21 seconds
• Errors: 0 (all 15 known issues prevented)
• Validation: ✅ Hugo + PaperMod + Sveltia + Workers deployed successfully

Complete Setup Checklist

Use this checklist to verify your setup:

• Hugo Extended v0.149.0+ installed (

  hugo version

  shows "+extended")
• Project created with

  --format yaml

  (hugo.yaml exists)
• Theme installed and configured (via Git submodule or Hugo Module)

• baseURL

  configured correctly in hugo.yaml

• .gitignore

  includes

  public/

  and

  resources/_gen/

• Sample content created and renders correctly
• Dev server runs without errors (

  hugo server

  )
• Production build succeeds (

  hugo --minify

  )
• wrangler.jsonc configured for Workers (if deploying)
• Sveltia CMS configured (if using CMS)
• GitHub Actions workflow configured (if using CI/CD)
• Deployed successfully (if deploying to Workers)

Questions? Issues?

1. Check

   references/error-catalog.md

   for all 15 documented errors and solutions
2. Verify all steps in the setup process
3. Use appropriate template from

   templates/

   directory
4. Load relevant reference guide for detailed information
5. Check official docs: https://gohugo.io/documentation/

This skill provides production-ready Hugo setup with zero errors. All 15 common issues are documented and prevented.