Hugo

Hugo Static Site Generator

Status: Production Ready | Last Updated: 2026-08-03 Latest Version: hugo@0.164.0+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.164.0/hugo_extended_0.164.0_linux-amd64.deb
sudo dpkg -i hugo_extended_0.164.0_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) - better CMS compatibility than TOML ✅ Add themes as Git submodules - easier updates and version control ✅ Set correct baseURL - prevents broken asset links on deployment ✅ Pin Hugo version in CI/CD - prevents version mismatch errors between local and deployment ✅ Add public/ to .gitignore - build output should not be committed ✅ Use draft: false - drafts don't appear in production builds ✅ Clone with --recursive flag - ensures theme submodules are fetched ✅ Use relative paths for images - /images/photo.jpg not ../images/photo.jpg ✅ Test build before deploying - catch errors locally with 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/ directory - it's generated output, not source code ❌ Don't use different Hugo versions - local vs CI/CD version mismatch causes errors ❌ Don't forget submodules: recursive - themes won't load in CI/CD ❌ Don't hardcode production URLs - use -b $CF_PAGES_URL or environment configs ❌ Don't push resources/_gen/ - generated assets, should be in .gitignore ❌ Don't use future dates carelessly - posts won't publish until date passes ❌ Don't skip .hugo_build.lock - add to .gitignore ❌ Don't mix YAML and TOML - stick to one format throughout project

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 Prevention: Always install Hugo Extended edition. Verify with hugo version | grep extended See: references/error-catalog.md for full error list

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 See: references/error-catalog.md #2

Error #3: Theme Not Found Errors

Error: Error: module "PaperMod" not found, blank site Prevention: Set theme: "PaperMod" in hugo.yaml and run git submodule update --init --recursive See: references/error-catalog.md #6

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 #4

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 to checkout action in GitHub Actions See: references/error-catalog.md #11

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/ Theme: PaperMod Time to deploy: 10 minutes Features: Search, tags, dark mode, RSS, Sveltia CMS

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 → Pattern 1