/hugo

name: hugo
description: "Hugo static site generator with Tailwind v4, headless CMS (Sveltia/Tina), Cloudflare deployment. Use for blogs, docs sites, or encountering theme installation, frontmatter, baseURL errors."
license: MIT
metadata:
  version: "2.0.0"
  hugo_version: "0.164.0"
  tailwind_version: "4.1.16"
  last_verified: "2026-08-03"
  production_tested: true
  token_savings: "60-65%"
  errors_prevented: 15
  templates_included: 4
  references_included: 6
  keywords:
    - hugo
    - hugo-extended
    - static-site-generator
    - ssg
    - go-templates
    - papermod
    - goldmark
    - markdown
    - blog
    - documentation
    - docs-site
    - landing-page
    - sveltia-cms
    - tina-cms
    - headless-cms
    - cloudflare-workers
    - workers-static-assets
    - wrangler
    - hugo-server
    - hugo-build
    - frontmatter
    - yaml-frontmatter
    - toml-config
    - hugo-themes
    - hugo-modules
    - multilingual
    - i18n
    - github-actions
    - version-mismatch
    - baseurl-error
    - theme-not-found
    - tailwind
    - tailwind-v4
    - tailwind-css
    - hugo-pipes
    - postcss
    - css-framework
    - utility-css
    - hugo-tailwind
    - tailwind-integration
    - hugo-assets

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 loca