hugo

What this skill does

# Hugo Static Site Generator

**Status**: Production Ready | **Last Updated**: 2025-11-21
**Latest Version**: [email protected]+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.

```bash
# 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

```bash
# 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

```yaml
# 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
```

```bash
# 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:**
```bash
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 wh