hugo

What this skill does

# Hugo Static Site Generator

**Status**: Production Ready
**Last Updated**: 2025-11-04
**Dependencies**: None (Hugo is a standalone binary)
**Latest Versions**: [email protected]+extended, PaperMod@latest, Sveltia CMS@latest

---

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

---

## The 7-Step Setup Process

### Step 1: Installation and Verification

**Install Hugo Extended** using one of these methods:

**Method 1: Homebrew (macOS/Linux)** ✅ Recommended
```bash
brew install hugo
```

**Method 2: Binary Download (Linux)**
```bash
# Check latest version: https://github.com/gohugoio/hugo/releases
VERSION="0.152.2"
wget https://github.com/gohugoio/hugo/releases/download/v${VERSION}/hugo_extended_${VERSION}_linux-amd64.deb
sudo dpkg -i hugo_extended_${VERSION}_linux-amd64.deb
```

**Method 3: Docker**
```bash
docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-alpine
```

**Method 4: NPM Wrapper** (not recommended, may lag behind)
```bash
npm install -g hugo-bin
```

**Verification:**
```bash
hugo version
# Should output: hugo v0.152.2+extended
#                                ^^^^^^^^ Must show "+extended"
```

**Key Points:**
- Extended edition required for SCSS/Sass
- Version should be v0.149.0+ for best compatibility
- NPM wrapper may be behind official releases
- Pin version in CI/CD (see Step 7)

### Step 2: Project Scaffolding

**Create new site with YAML configuration:**

```bash
hugo new site my-site --format yaml
cd my-site
```

**Directory structure created:**
```
my-site/
├── hugo.yaml          # Configuration (YAML format)
├── archetypes/        # Content templates
│   └── default.md
├── content/           # All your content goes here
├── data/              # Data files (JSON/YAML/TOML)
├── layouts/           # Template overrides
├── static/            # Static assets (images, CSS, JS)
├── themes/            # Themes directory
└── public/            # Build output (generated, git ignore)
```

**CRITICAL:**
- Use `--format yaml` for CMS compatibility
- Never commit `public/` directory to Git
- Create `.gitignore` immediately (see Step 3)

### Step 3: Theme Installation

**Recommended Method: Git Submodule** ✅

```bash
# Popular themes:
# - PaperMod (blogs): https://github.com/adityatelange/hugo-PaperMod
# - Book (docs): https://github.com/alex-shpak/hugo-book
# - Academic (research): https://github.com/HugoBlox/theme-academic-cv
# - Ananke (general): https://github.com/theNewDynamic/gohugo-theme-ananke

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
```

**Alternative: Hugo Modules** (advanced)
```bash
hugo mod init github.com/username/my-site

# In hugo.yaml:
# module:
#   imports:
#     - path: github.com/adityatelange/hugo-PaperMod
```

**Add theme to hugo.yaml:**
```yaml
theme: "PaperMod"
```

**When cloning project with submodules:**
```bash
git clone --recursive https://github.com/username/my-site.git
# Or if already cloned:
git submodule update --init --recursive
```

**Key Points:**
- Git submodules are recommended over manual downloads
- `--depth=1` saves space (no theme history)
- Always run `git submodule update --init --recursive` after clone
- Hugo Modules are more advanced but don't require Git submodules

### Step 4: Configuration

**hugo.yaml - Complete Example (PaperMod blog):**

```yaml
baseURL: "https://example.com/"
title: "My Hugo Blog"
theme: "PaperMod"
languageCode: "en-us"
defaultContentLanguage: "en"
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  author: "Your Name"
  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  defaultTheme: auto  # dark, light, auto

  socialIcons:
    - name: twitter
      url: "https://twitter.com/username"
    - name: github
      url: "https://github.com/username"

menu:
  main:
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 10
    - identifier: about
      name: About
      url: /about/
      weight: 20

outputs:
  home:
    - HTML
    - RSS
    - JSON  # Required for search
```

**Configuration Formats:**
- **YAML** (recommended): `hugo.yaml` - Better CMS compatibility
- **TOML** (legacy): `hugo.toml` - Default but problematic with Sveltia CMS
- **JSON**: `hugo.json` - Rarely used

**Environment-Specific Configs:**
```
config/
├── _default/
│   └── hugo.yaml
├── production/
│   └── hugo.yaml  # Overrides for production
└── development/
    └── hugo.yaml  # Overrides for local dev
```

### Step 5: Content Creation

**Create content with Hugo CLI:**
```bash
# Blog post
hugo new content posts/my-first-post.md

# Page
hugo new content about.md

# Nested documentation
hugo new content docs/getting-started/installation.md
```

**Frontmatter Format (YAML recommended):**

```yaml
---
title: "My First Post"
date: 2025-11-04T10:00:00+11:00
draft: false
tags: ["hugo", "blog"]
categories: ["General"]
description: "A brief description for SEO"
cover:
  image: "/images/cover.jpg"
  alt: "Cover image"
---

# Post content starts here

This is my first Hugo blog post!
```

**TOML Frontmatter (for reference only):**
```toml
+++
title = "My First Post"
date = 2025-11-04T10:00:00+11:00
draft = false
tags = ["hugo", "blog"]
+++
```

**Key Points:**
- Use `---` delimiters for YAML frontmatter
- Use `+++` delimiters for TOML frontmatter
- `draft: false` required for post to appear in production
- `date` in future = post won't publish (unless `--buildFuture` flag used)
- Content goes after frontmatter closing delimiter

### Step 6: Build and Development

**Development server (with live reload):**
```bash
# Start server
hugo server

# With drafts visible
hugo server --buildDrafts

# With future-dated posts
hugo server --buildFuture

# Bind to specific port
hugo server --port 1314

# Access at: http://localhost:1313
```

**Production build:**
```bash
# Basic build
hugo

# With minification (recommended)
hugo --minify

# With specific baseURL (for deployment)
hugo --minify --baseURL https://example.com

# Or use en