hugo

Original：🇺🇸 English

Translated

This skill provides comprehensive knowledge for building static websites with Hugo static site generator. It should be used when setting up Hugo projects (blogs, documentation sites, landing pages, portfolios), integrating Tailwind CSS v4 for custom styling, integrating headless CMS systems (Sveltia CMS or TinaCMS), deploying to Cloudflare Workers with Static Assets, configuring themes and templates, and preventing common Hugo setup errors. Use this skill when encountering these scenarios: scaffolding new Hugo sites, choosing between Hugo Extended and Standard editions, integrating Tailwind CSS v4 with Hugo Pipes, configuring hugo.yaml or hugo.toml files, integrating PaperMod or other themes via Git submodules, setting up Sveltia CMS or TinaCMS for content management, deploying to Cloudflare Workers or Pages, troubleshooting baseURL configuration, resolving theme installation errors, fixing frontmatter format issues (YAML vs TOML), preventing date-related build failures, setting up PostCSS with Hugo, or setting up CI/CD with GitHub Actions. 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

1installs

Sourcejackspace/claudeskillz

Added on2026-02-07

NPX Install

npx skill4agent add jackspace/claudeskillz hugo

SKILL.md Content

View Translation Comparison →

Hugo Static Site Generator

Status: Production Ready Last Updated: 2025-11-04 Dependencies: None (Hugo is a standalone binary) Latest Versions: hugo@0.152.2+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 environment variable
hugo --minify -b $CF_PAGES_URL

Build Output:

All generated files go to
```
public/
```
directory
Typical build time: <100ms for small sites, <5s for 1000+ pages
Hugo is the fastest static site generator

Key Points:

Development server has live reload (HMR)
Production build should use
```
--minify
```
Never commit
```
public/
```
directory
Build time is extremely fast (Hugo is written in Go)

Step 7: Cloudflare Workers Deployment

Create wrangler.jsonc:

jsonc

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

Manual deployment:

bash

# Build site
hugo --minify

# Deploy to Workers
npx wrangler deploy

GitHub Actions (Automated):

Create

.github/workflows/deploy.yml

yaml

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Important for theme submodules!

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.152.2'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Key Points:

```
assets.directory
```
must be
```
"./public"
```
(Hugo's output)
```
html_handling: "auto-trailing-slash"
```
handles Hugo's URL structure
```
not_found_handling: "404-page"
```
serves Hugo's 404.html
Always pin Hugo version in CI/CD (prevents version mismatch errors)
Use
```
submodules: recursive
```
for theme submodules

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

Known Issues Prevention

This skill prevents 9 documented issues:

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

Error:

Error: SCSS support not enabled

Source: https://gohugo.io/troubleshooting/faq/#i-get-this-feature-is-not-available-in-your-current-hugo-version Why It Happens: Theme requires SCSS/Sass processing, but Hugo Standard doesn't include it Prevention: Always install Hugo Extended edition. Verify with

hugo version | grep extended

Issue #2: baseURL Configuration Errors

Error: Broken CSS/JS/image links, 404s on all assets Source: Hugo docs, Cloudflare Pages guide Why It Happens:

baseURL

in config doesn't match deployment URL Prevention:

Use environment-specific configs (
```
config/production/hugo.yaml
```
)
Or use build flag:
```
hugo -b $CF_PAGES_URL
```
Or set correct baseURL in hugo.yaml before build

Issue #3: TOML vs YAML Configuration Confusion

Error: Sveltia CMS fails to parse frontmatter, config not loading Source: Sveltia CMS documentation, community reports Why It Happens: Mixing TOML and YAML, or using TOML with Sveltia CMS (which has bugs) Prevention: Standardize on YAML format. Create sites with

--format yaml

flag

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

Error: Features work locally but fail in CI/CD, or vice versa Source: GitHub Actions hugo-setup, Cloudflare Pages docs Why It Happens: Different Hugo versions have different features/bugs Prevention:

Pin Hugo version in
```
hugo.yaml
```
metadata or README
Set
```
HUGO_VERSION
```
in Cloudflare Pages
Use
```
hugo-version: '0.152.2'
```
in GitHub Actions

Issue #5: Content Frontmatter Format Errors

Error: Content files don't render, build fails with parse errors Source: Hugo content management documentation Why It Happens: Wrong delimiters (

---

+++

), invalid YAML/TOML syntax Prevention:

YAML: use
```
---
```
delimiters
TOML: use
```
+++
```
delimiters
Validate frontmatter with Sveltia CMS or YAML linter

Issue #6: Theme Not Found Errors

Error:

Error: module "PaperMod" not found

, blank site Source: Hugo themes documentation Why It Happens: Theme not installed, or

theme

not set in config, or Git submodules not initialized Prevention:

Set
```
theme: "PaperMod"
```
in hugo.yaml
Use
```
git submodule add
```
for theme installation
Always
```
git submodule update --init --recursive
```
after clone

Issue #7: Date Time Warp Issues

Error: Content missing on deployed site but visible locally Source: Hugo date handling documentation Why It Happens: Future-dated posts published locally (with

--buildFuture

) but not in production Prevention:

Use current or past dates in frontmatter
Or add
```
--buildFuture
```
flag to production build
Check
```
date
```
field in frontmatter

Issue #8: Public Folder Conflicts

Error: Stale content on site, Git conflicts in

public/

Source: Hugo project structure best practices Why It Happens: Committing

public/

directory when it should be build output only Prevention:

Add
```
public/
```
to
```
.gitignore
```
Rebuild on every deployment
Never commit generated files

Issue #9: Module Cache Issues

Error:

failed to extract shortcode

, corrupted module cache Source: Hugo modules documentation, GitHub issues Why It Happens: Corrupted Hugo Modules cache (when using modules instead of submodules) Prevention:

Run
```
hugo mod clean
```
to clear cache
Run
```
hugo mod tidy
```
periodically
Or use Git submodules instead of modules (more reliable)

Configuration Files Reference

hugo.yaml (Full Production Example)

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
pygmentsUseClasses: true
summaryLength: 30

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production
  title: "My Hugo Blog"
  description: "A blog built with Hugo and PaperMod"
  keywords: [Blog, Hugo, Tech]
  author: "Your Name"
  images: ["/images/og-image.jpg"]
  DateFormat: "January 2, 2006"
  defaultTheme: auto  # dark, light, auto
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: true
  tocopen: false

  assets:
    disableHLJS: true
    disableFingerprinting: false

  label:
    text: "My Hugo Blog"
    icon: /favicon.ico
    iconHeight: 35

  homeInfoParams:
    Title: "Hi there 👋"
    Content: Welcome to my blog.

  socialIcons:
    - name: twitter
      url: "https://twitter.com/"
    - name: github
      url: "https://github.com/"
    - name: linkedin
      url: "https://linkedin.com/"
    - name: rss
      url: "/index.xml"

  cover:
    hidden: false
    hiddenInList: false
    hiddenInSingle: false

  editPost:
    URL: "https://github.com/username/repo/tree/main/content"
    Text: "Suggest Changes"
    appendFilePath: true

  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    keys: ["title", "permalink", "summary", "content"]

menu:
  main:
    - identifier: search
      name: Search
      url: /search/
      weight: 10
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 20
    - identifier: archives
      name: Archives
      url: /archives/
      weight: 30
    - identifier: tags
      name: Tags
      url: /tags/
      weight: 40
    - identifier: about
      name: About
      url: /about/
      weight: 50

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

Why these settings:

```
buildDrafts: false
```
- prevents drafts in production
```
enableRobotsTXT: true
```
- SEO best practice
```
minifyOutput: true
```
- smaller file sizes
```
defaultTheme: auto
```
- respects user's system preference
```
JSON
```
output - enables client-side search
Social icons - improves discoverability

wrangler.jsonc (Cloudflare Workers)

jsonc

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

Why these settings:

```
directory: "./public"
```
- Hugo's build output
```
html_handling: "auto-trailing-slash"
```
- matches Hugo's URL structure
```
not_found_handling: "404-page"
```
- serves Hugo's custom 404.html

.gitignore (Essential)

gitignore

# Hugo
/public/
/resources/_gen/
.hugo_build.lock

# OS
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/
*.swp
*.swo

# Dependencies (if using npm for tools)
node_modules/
package-lock.json

# Logs
*.log

Sveltia CMS Integration (Recommended)

Why Sveltia CMS for Hugo?

✅ Hugo is Sveltia's primary use case - designed specifically for Hugo ✅ Simple setup - 2 static files, no build step required ✅ No npm dependencies - single CDN script ✅ Local backend - test CMS locally without Git ✅ YAML frontmatter - fully compatible ✅ No security vulnerabilities - lightweight, maintained ✅ Active development - focused on static site generators

Setup (5 Minutes)

1. Create admin interface -

static/admin/index.html

html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Content Manager</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
  </body>
</html>

2. Create CMS config -

static/admin/config.yml

yaml

backend:
  name: git-gateway
  branch: main

local_backend: true  # Enable local testing

media_folder: "static/images/uploads"
public_folder: "/images/uploads"

collections:
  - name: "blog"
    label: "Blog Posts"
    folder: "content/posts"
    create: true
    slug: "{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Description", name: "description", widget: "string", required: false}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Tags", name: "tags", widget: "list", required: false}
      - {label: "Categories", name: "categories", widget: "list", required: false}
      - {label: "Cover Image", name: "cover", widget: "object", required: false, fields: [
          {label: "Image", name: "image", widget: "image", required: false},
          {label: "Alt Text", name: "alt", widget: "string", required: false}
        ]}
      - {label: "Body", name: "body", widget: "markdown"}

  - name: "pages"
    label: "Pages"
    folder: "content"
    create: true
    slug: "{{slug}}"
    filter: {field: "type", value: "page"}
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Type", name: "type", widget: "hidden", default: "page"}
      - {label: "Draft", name: "draft", widget: "boolean", default: false}
      - {label: "Body", name: "body", widget: "markdown"}

3. Rebuild site:

bash

hugo
# Admin interface now at: http://localhost:1313/admin

4. Production OAuth (for Git backend):

Sveltia CMS needs OAuth for GitHub/GitLab authentication in production. Use Cloudflare Workers for OAuth proxy:

See bundled reference:

references/sveltia-integration-guide.md

Key Points:

Admin accessible at
```
/admin
```
after build
```
local_backend: true
```
allows local testing without Git
YAML frontmatter format required
Collections map to Hugo content directories
Media files saved to
```
static/images/uploads
```

TinaCMS Integration (Not Recommended)

⚠️ Use Sveltia CMS instead. TinaCMS has significant limitations for Hugo:

Why Not TinaCMS?

❌ React-only visual editing - Hugo is Go-templated, visual editing won't work ❌ Complex setup - requires Node.js server or Tina Cloud ❌ 692 npm packages - vs Sveltia's 1 CDN script ❌ 7 security vulnerabilities - (4 high, 3 critical as of 2025-11-04) ❌ React/Next.js focused - Hugo is secondary use case ❌ YAML only - same limitation as Sveltia, without benefits

If You Must Use TinaCMS

Only consider TinaCMS if:

Already using Tina Cloud
Have React expertise available
Need Tina-specific features

See bundled reference:

references/tinacms-integration-guide.md

(warning: not recommended)

Tailwind CSS v4 Integration

Hugo supports Tailwind CSS v4 through Hugo Pipes and the Tailwind CLI. This approach is fundamentally different from Vite-based React projects.

When to Use Tailwind vs Themes

Use Tailwind with Hugo when:

Building custom designs without relying on themes
Need utility-first CSS workflow
Want complete styling control
Prefer Tailwind over SCSS/Sass

Use themes (PaperMod, Book, etc.) when:

Want proven, production-ready designs
Need fast setup without custom CSS
Happy with theme customization options
Don't need pixel-perfect custom design

Key Differences from Vite + React

CRITICAL: Do NOT try to use the

tailwind-v4-shadcn

skill patterns with Hugo. That skill is for Vite + React projects and is incompatible with Hugo's asset pipeline.

Aspect	Vite + React	Hugo
Build System	JavaScript (Node.js)	Go (Hugo binary)
Tailwind Integration	`@tailwindcss/vite` plugin	Tailwind CLI + PostCSS
Config File	`vite.config.ts`	`hugo.yaml`
Content Scanning	`content: []` globs	`hugo_stats.json`
Dev Server	Vite (port 5173)	Hugo (port 1313)
Dark Mode	React ThemeProvider	CSS classes or Alpine.js

Quick Start (10 Minutes)

Install Dependencies

bash

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

Configure Hugo (
```
hugo.yaml
```
)

yaml

build:
  writeStats: true  # Generates hugo_stats.json for Tailwind

module:
  mounts:
    - source: assets
      target: assets
    - source: hugo_stats.json
      target: assets/watching/hugo_stats.json

Configure Tailwind (
```
tailwind.config.js
```
)

javascript

module.exports = {
  content: [
    './hugo_stats.json',
    './layouts/**/*.html',
    './content/**/*.{html,md}',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: '#0066cc',
      },
    },
  },
  plugins: [],
}

Configure PostCSS (
```
postcss.config.js
```
)

javascript

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Create CSS Entry File (
```
assets/css/main.css
```
)

css

@import "tailwindcss";

@layer base {
  body {
    @apply bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100;
  }
}

Process CSS in Template (
```
layouts/_default/baseof.html
```
)

html

<head>
  {{ $style := resources.Get "css/main.css" | resources.PostCSS }}
  {{ if hugo.IsProduction }}
    {{ $style = $style | minify | fingerprint }}
  {{ end }}
  <link rel="stylesheet" href="{{ $style.RelPermalink }}">
</head>

Start Development

bash

hugo server

Complete Integration Guide

For full Tailwind v4 + Hugo setup including:

Dark mode implementation (CSS-only and Alpine.js)
Typography plugin setup
Forms plugin setup
Template integration patterns
Common issues and solutions
Production build optimization

See bundled resources:

Reference Guide:
```
references/tailwind-v4-integration.md
```
(comprehensive documentation)
Minimal Template:
```
templates/hugo-tailwind-minimal/
```
(starting point)
Blog Template:
```
templates/hugo-tailwind-blog/
```
(complete blog with Tailwind)

Tailwind-Specific Issues

Common issues when using Tailwind with Hugo (all documented with solutions in reference guide):

Issue	Cause	Solution
CSS not processing	PostCSS not configured	Verify `resources.PostCSS` in template
Classes not purging	`hugo_stats.json` not generated	Enable `writeStats: true` in `hugo.yaml`
Dark mode broken	Wrong config	Use `darkMode: 'class'` in `tailwind.config.js`
Asset fingerprinting fails	Incorrect Hugo Pipes usage	Use `RelPermalink` not `Permalink`
Hugo template syntax in CSS	Can't use `{{ }}` in CSS	Apply classes in templates, not CSS
Version mismatch	CLI vs PostCSS plugin	Update all to same version

Common Patterns

Pattern 1: Blog with PaperMod Theme

bash

# Scaffold
hugo new site my-blog --format yaml
cd my-blog
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# Configure (see hugo.yaml example above)

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

# Develop
hugo server

# Build
hugo --minify

When to use: Personal blogs, company blogs, news sites

Pattern 2: Documentation Site with Hugo Book

bash

# Scaffold
hugo new site docs --format yaml
cd docs
git init
git submodule add https://github.com/alex-shpak/hugo-book.git themes/hugo-book

# Configure for docs (nested navigation, search)
# See: bundled template `templates/hugo-docs/`

# Create docs
hugo new content docs/getting-started/installation.md

# Build
hugo --minify

When to use: Technical documentation, knowledge bases, API docs

Pattern 3: Landing Page

bash

# Scaffold
hugo new site landing --format yaml

# Use custom layouts (no theme)
# See: bundled template `templates/hugo-landing/`

# Single-page structure
hugo new content _index.md

# Build
hugo --minify

When to use: Marketing sites, product pages, portfolios

Pattern 4: Multilingual Site

yaml

# hugo.yaml
defaultContentLanguage: "en"
languages:
  en:
    languageName: "English"
    weight: 1
  es:
    languageName: "Español"
    weight: 2

# Content structure:
# content/
# ├── posts/
# │   └── post-1.en.md
# │   └── post-1.es.md

When to use: International sites, localized content

Using Bundled Resources

Scripts (scripts/)

init-hugo.sh
- Automated Hugo project setup

bash

./scripts/init-hugo.sh blog my-blog
# Creates Hugo site with specified template (blog/docs/landing/minimal)
# Arguments: [template-type] [project-name]

deploy-workers.sh
- Manual Cloudflare Workers deployment

bash

./scripts/deploy-workers.sh
# Runs: hugo --minify && wrangler deploy

check-versions.sh
- Verify Hugo and tool versions

bash

./scripts/check-versions.sh
# Checks: Hugo version, Extended edition, wrangler, Node.js

Templates (templates/)

Complete, working 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
GitHub Actions workflow

templates/hugo-docs/
- Documentation site

Nested navigation, search, breadcrumbs
Hugo Book theme
Sveltia CMS for docs editing

templates/hugo-landing/
- Landing page

Hero, features, testimonials, CTA
Custom layouts (no theme)
Optimized for conversions

templates/minimal-starter/
- Bare-bones project

No theme, clean slate
Setup guide for adding themes
Minimal configuration

When to use templates: Copy entire template directory to start a new project instantly.

References (references/)

Detailed guides that Claude can load when needed:

```
references/sveltia-integration-guide.md
```
- Complete Sveltia CMS setup, OAuth configuration
```
references/workers-deployment-guide.md
```
- Cloudflare Workers deployment, CI/CD, custom domains
```
references/common-errors.md
```
- All 9 errors with detailed solutions
```
references/theme-customization-guide.md
```
- Overriding layouts, custom CSS, partials
```
references/hugo-vs-alternatives.md
```
- Comparison with Next.js, Astro, Jekyll

When Claude should load these: User asks about specific topics (CMS setup, deployment, errors, theming, alternatives)

Assets (assets/)

```
assets/screenshots/
```
- Visual examples of Hugo blog, Sveltia CMS, deployment
```
assets/diagrams/
```
- Hugo directory structure, deployment workflow diagrams

Advanced Topics

Custom Shortcodes

Create reusable content components:

<!-- layouts/shortcodes/youtube.html -->
<div class="youtube-embed">
  <iframe
    src="https://www.youtube.com/embed/{{ .Get 0 }}"
    allowfullscreen>
  </iframe>
</div>

Usage in content:

markdown

{{< youtube dQw4w9WgXcQ >}}

Image Processing

Hugo has built-in image processing:

{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x" }}
<img src="{{ $resized.RelPermalink }}" alt="Photo">

Taxonomy Customization

Create custom taxonomies beyond tags/categories:

yaml

# hugo.yaml
taxonomies:
  tag: tags
  category: categories
  series: series  # Custom taxonomy

Data Files

Use JSON/YAML/TOML data files:

yaml

# data/team.yaml
- name: Alice
  role: Developer
- name: Bob
  role: Designer

Access in templates:

{{ range .Site.Data.team }}
  <div>{{ .name }} - {{ .role }}</div>
{{ end }}

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
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 9 known issues prevented)
Validation: ✅ Hugo + PaperMod + Sveltia + Workers deployed successfully

Troubleshooting

Problem: "SCSS support not enabled" error

Solution: Install Hugo Extended, not Standard. Verify with

hugo version | grep extended

Problem: Blank site after deployment

Solution:

Check
```
theme
```
is set in hugo.yaml
Verify theme exists in
```
themes/
```
directory
Run
```
git submodule update --init --recursive
```

Problem: Assets (CSS/JS/images) not loading

Solution:

Check
```
baseURL
```
in hugo.yaml matches deployment URL
Or use
```
hugo -b https://your-site.com
```
Or use environment-specific config

Problem: Posts not appearing on site

Solution:

Check
```
draft: false
```
in frontmatter
Check date is not in future
Or build with
```
--buildDrafts
```
and
```
--buildFuture
```
flags

Problem: Theme not found in CI/CD

Solution: Add

submodules: recursive

to checkout action in GitHub Actions

Problem: Sveltia CMS not loading

Solution:

Rebuild site with
```
hugo
```
Check
```
/admin
```
directory exists in
```
public/
```
Verify
```
config.yml
```
syntax
Check browser console for errors

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?

Check
```
references/common-errors.md
```
for all 9 documented errors and solutions
Verify all steps in the setup process
Check official docs: https://gohugo.io/documentation/
Ensure Hugo Extended is installed (most common issue)

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