Hugo 静态网站生成器完整指南：5分钟快速上手与7步设置流程

hugo by jackspace/claudeskillz

87 周安装量

14 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jackspace/claudeskillz --skill hugo

开发文档生成静态分析

🇨🇳中文介绍

Hugo 静态网站生成器

状态：生产就绪 最后更新：2025-11-04 依赖项：无（Hugo 是独立的二进制文件） 最新版本：hugo@0.152.2+extended, PaperMod@latest, Sveltia CMS@latest

快速开始（5分钟）

1. 安装 Hugo Extended 版本

关键：除非你确定不需要 SCSS/Sass 支持，否则始终安装 Hugo Extended 版本（而不是 Standard 标准版）。大多数主题都需要 Extended 版本。

# 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

# 验证 Extended 版本
hugo version  # 应显示 "+extended"

为何重要：

Hugo Extended 包含 SCSS/Sass 处理功能
大多数流行主题（PaperMod、Academic、Docsy）都需要 Extended 版本
Standard 版本会出现 "SCSS support not enabled" 错误
Extended 版本没有缺点（速度相同，功能相同且更多）

2. 创建新的 Hugo 站点

# 使用 YAML 格式（而非 TOML）以获得更好的 CMS 兼容性
hugo new site my-blog --format yaml

# 初始化 Git
cd my-blog
git init

# 添加 PaperMod 主题（博客推荐）
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 1：安装和验证

使用以下方法之一安装 Hugo Extended：

方法 1：Homebrew (macOS/Linux) ✅ 推荐

方法 2：二进制下载 (Linux)

# 检查最新版本：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

方法 3：Docker

docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-alpine

方法 4：NPM 包装器（不推荐，可能落后于官方版本）

npm install -g hugo-bin

hugo version
# 应输出：hugo v0.152.2+extended
#                                ^^^^^^^^ 必须显示 "+extended"

Extended 版本是 SCSS/Sass 所必需的
版本应为 v0.149.0+ 以获得最佳兼容性
NPM 包装器可能落后于官方发布
在 CI/CD 中固定版本（见步骤 7）

步骤 2：项目脚手架

使用 YAML 配置创建新站点：

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

创建的目录结构：

my-site/
├── hugo.yaml          # 配置（YAML 格式）
├── archetypes/        # 内容模板
│   └── default.md
├── content/           # 所有内容放在这里
├── data/              # 数据文件（JSON/YAML/TOML）
├── layouts/           # 模板覆盖
├── static/            # 静态资源（图片、CSS、JS）
├── themes/            # 主题目录
└── public/            # 构建输出（生成，git 忽略）

使用 --format yaml 以获得 CMS 兼容性
切勿将 public/ 目录提交到 Git
立即创建 .gitignore（见步骤 3）

步骤 3：主题安装

推荐方法：Git 子模块 ✅

# 流行主题：
# - PaperMod (博客)：https://github.com/adityatelange/hugo-PaperMod
# - Book (文档)：https://github.com/alex-shpak/hugo-book
# - Academic (研究)：https://github.com/HugoBlox/theme-academic-cv
# - Ananke (通用)：https://github.com/theNewDynamic/gohugo-theme-ananke

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

替代方案：Hugo 模块（高级）

hugo mod init github.com/username/my-site

# 在 hugo.yaml 中：
# module:
#   imports:
#     - path: github.com/adityatelange/hugo-PaperMod

将主题添加到 hugo.yaml：

克隆带有子模块的项目时：

git clone --recursive https://github.com/username/my-site.git
# 或者如果已经克隆：
git submodule update --init --recursive

推荐使用 Git 子模块而非手动下载
--depth=1 节省空间（不包含主题历史记录）
克隆后始终运行 git submodule update --init --recursive
Hugo 模块更高级，但不需要 Git 子模块

hugo.yaml - 完整示例（PaperMod 博客）：

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  # 搜索所需

YAML（推荐）：hugo.yaml - 更好的 CMS 兼容性
TOML（旧版）：hugo.toml - 默认，但在 Sveltia CMS 中有问题
JSON：hugo.json - 很少使用

环境特定配置：

config/
├── _default/
│   └── hugo.yaml
├── production/
│   └── hugo.yaml  # 生产环境覆盖配置
└── development/
    └── hugo.yaml  # 本地开发覆盖配置

步骤 5：内容创建

使用 Hugo CLI 创建内容：

# 博客文章
hugo new content posts/my-first-post.md

# 页面
hugo new content about.md

# 嵌套文档
hugo new content docs/getting-started/installation.md

Frontmatter 格式（推荐 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"
---

# 文章内容从这里开始

This is my first Hugo blog post!

TOML Frontmatter（仅作参考）：

+++
title = "My First Post"
date = 2025-11-04T10:00:00+11:00
draft = false
tags = ["hugo", "blog"]
+++

使用 --- 作为 YAML frontmatter 的分隔符
使用 +++ 作为 TOML frontmatter 的分隔符
draft: false 是文章出现在生产环境所必需的
date 在未来 = 文章不会发布（除非使用 --buildFuture 标志）
内容放在 frontmatter 结束分隔符之后

步骤 6：构建和开发

开发服务器（带实时重载）：

# 启动服务器
hugo server

# 显示草稿
hugo server --buildDrafts

# 显示未来日期的文章
hugo server --buildFuture

# 绑定到特定端口
hugo server --port 1314

# 访问地址：http://localhost:1313

生产环境构建：

# 基本构建
hugo

# 带压缩（推荐）
hugo --minify

# 带特定 baseURL（用于部署）
hugo --minify --baseURL https://example.com

# 或使用环境变量
hugo --minify -b $CF_PAGES_URL

所有生成的文件都放在 public/ 目录中
典型构建时间：小型站点 <100ms，1000+ 页面 <5s
Hugo 是最快的静态网站生成器

开发服务器具有实时重载（HMR）
生产环境构建应使用 --minify
切勿提交 public/ 目录
构建时间极快（Hugo 使用 Go 编写）

步骤 7：Cloudflare Workers 部署

创建 wrangler.jsonc：

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

# 构建站点
hugo --minify

# 部署到 Workers
npx wrangler deploy

GitHub Actions（自动化）：

创建 .github/workflows/deploy.yml：

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  # 主题子模块很重要！

      - 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 }}

assets.directory 必须是 "./public"（Hugo 的输出目录）
html_handling: "auto-trailing-slash" 处理 Hugo 的 URL 结构
not_found_handling: "404-page" 提供 Hugo 的 404.html
在 CI/CD 中始终固定 Hugo 版本（防止版本不匹配错误）
对于主题子模块，使用 submodules: recursive

✅ 安装 Hugo Extended（而非 Standard） - 主题的 SCSS/Sass 支持所必需 ✅ 使用 YAML 配置（--format yaml） - 比 TOML 具有更好的 CMS 兼容性 ✅ 将主题添加为 Git 子模块 - 更易于更新和版本控制 ✅ 设置正确的 baseURL - 防止部署时资源链接损坏 ✅ 在 CI/CD 中固定 Hugo 版本 - 防止本地和部署环境之间的版本不匹配错误 ✅ 将 public/ 添加到 .gitignore - 构建输出不应提交 ✅ 使用 draft: false - 草稿不会出现在生产环境构建中 ✅ 使用 --recursive 标志克隆 - 确保获取主题子模块 ✅ 对图片使用相对路径 - /images/photo.jpg 而非 ../images/photo.jpg ✅ 部署前测试构建 - 使用 hugo --minify 在本地捕获错误

❌ 不要安装 Hugo Standard - 大多数主题需要 Extended 版本 ❌ 不要将 TOML 配置与 Sveltia CMS 一起使用 - 存在已知错误，请使用 YAML ❌ 不要提交 public/ 目录 - 它是生成的输出，不是源代码 ❌ 不要使用不同的 Hugo 版本 - 本地与 CI/CD 版本不匹配会导致错误 ❌ 不要忘记 submodules: recursive - 主题在 CI/CD 中无法加载 ❌ 不要硬编码生产环境 URL - 使用 -b $CF_PAGES_URL 或环境配置 ❌ 不要推送 resources/_gen/ - 生成的资源，应放在 .gitignore 中 ❌ 不要随意使用未来日期 - 文章在日期过去之前不会发布 ❌ 不要跳过 .hugo_build.lock - 添加到 .gitignore ❌ 不要混合使用 YAML 和 TOML - 在整个项目中坚持使用一种格式

此技能可预防 9 个已记录的问题：

问题 #1：版本不匹配（Hugo 与 Hugo Extended）

错误：Error: SCSS support not enabled 来源：https://gohugo.io/troubleshooting/faq/#i-get-this-feature-is-not-available-in-your-current-hugo-version 发生原因：主题需要 SCSS/Sass 处理，但 Hugo Standard 不包含此功能预防：始终安装 Hugo Extended 版本。使用 hugo version | grep extended 验证

问题 #2：baseURL 配置错误

错误：CSS/JS/图片链接损坏，所有资源 404 来源：Hugo 文档，Cloudflare Pages 指南 发生原因：配置中的 baseURL 与部署 URL 不匹配预防：

使用环境特定配置（config/production/hugo.yaml）
或使用构建标志：hugo -b $CF_PAGES_URL
或在构建前在 hugo.yaml 中设置正确的 baseURL

问题 #3：TOML 与 YAML 配置混淆

错误：Sveltia CMS 无法解析 frontmatter，配置未加载来源：Sveltia CMS 文档，社区报告 发生原因：混合使用 TOML 和 YAML，或将 TOML 与 Sveltia CMS 一起使用（存在错误）预防：标准化使用 YAML 格式。使用 --format yaml 标志创建站点

问题 #4：Hugo 版本不匹配（本地与部署）

错误：功能在本地有效但在 CI/CD 中失败，反之亦然来源：GitHub Actions hugo-setup，Cloudflare Pages 文档 发生原因：不同的 Hugo 版本具有不同的功能/错误预防：

在 hugo.yaml 元数据或 README 中固定 Hugo 版本
在 Cloudflare Pages 中设置 HUGO_VERSION
在 GitHub Actions 中使用 hugo-version: '0.152.2'

问题 #5：内容 Frontmatter 格式错误

错误：内容文件未渲染，构建因解析错误而失败来源：Hugo 内容管理文档 发生原因：错误的分隔符（--- 与 +++），无效的 YAML/TOML 语法预防：

YAML：使用 --- 分隔符
TOML：使用 +++ 分隔符
使用 Sveltia CMS 或 YAML 检查器验证 frontmatter

问题 #6：主题未找到错误

错误：Error: module "PaperMod" not found，空白站点来源：Hugo 主题文档 发生原因：主题未安装，或配置中未设置 theme，或 Git 子模块未初始化预防：

在 hugo.yaml 中设置 theme: "PaperMod"
使用 git submodule add 安装主题
克隆后始终运行 git submodule update --init --recursive

问题 #7：日期时间扭曲问题

错误：部署站点上内容缺失但在本地可见来源：Hugo 日期处理文档 发生原因：未来日期的文章在本地发布（使用 --buildFuture）但未在生产环境发布预防：

在 frontmatter 中使用当前或过去的日期
或在生产环境构建中添加 --buildFuture 标志
检查 frontmatter 中的 date 字段

问题 #8：公共文件夹冲突

错误：站点上内容过时，public/ 中存在 Git 冲突来源：Hugo 项目结构最佳实践 发生原因：提交了 public/ 目录，而它应该只是构建输出预防：

将 public/ 添加到 .gitignore
每次部署时重新构建
切勿提交生成的文件

问题 #9：模块缓存问题

错误：failed to extract shortcode，模块缓存损坏来源：Hugo 模块文档，GitHub 问题 发生原因：损坏的 Hugo 模块缓存（当使用模块而非子模块时）预防：

运行 hugo mod clean 清除缓存
定期运行 hugo mod tidy
或使用 Git 子模块替代模块（更可靠）

hugo.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  # 搜索功能所需

为何使用这些设置：

buildDrafts: false - 防止草稿出现在生产环境
enableRobotsTXT: true - SEO 最佳实践
minifyOutput: true - 更小的文件大小
defaultTheme: auto - 尊重用户的系统偏好
JSON 输出 - 启用客户端搜索
社交图标 - 提高可发现性

wrangler.jsonc (Cloudflare Workers)

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

为何使用这些设置：

directory: "./public" - Hugo 的构建输出
html_handling: "auto-trailing-slash" - 匹配 Hugo 的 URL 结构
not_found_handling: "404-page" - 提供 Hugo 的自定义 404.html

.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 集成（推荐）

为何为 Hugo 选择 Sveltia CMS？

✅ Hugo 是 Sveltia 的主要用例 - 专门为 Hugo 设计 ✅ 简单设置 - 2 个静态文件，无需构建步骤 ✅ 无 npm 依赖 - 单个 CDN 脚本 ✅ 本地后端 - 无需 Git 即可在本地测试 CMS ✅ YAML frontmatter - 完全兼容 ✅ 无安全漏洞 - 轻量级，维护良好 ✅ 积极开发 - 专注于静态网站生成器

1. 创建管理界面 - static/admin/index.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. 创建 CMS 配置 - static/admin/config.yml：

backend:
  name: git-gateway
  branch: main

local_backend: true  # 启用本地测试

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. 重建站点：

hugo
# 管理界面现在位于：http://localhost:1313/admin

4. 生产环境 OAuth（用于 Git 后端）：

Sveltia CMS 在生产环境中需要 OAuth 进行 GitHub/GitLab 身份验证。使用 Cloudflare Workers 作为 OAuth 代理：

参见捆绑的参考文档：references/sveltia-integration-guide.md

构建后可在 /admin 访问管理界面
local_backend: true 允许无需 Git 进行本地测试
需要 YAML frontmatter 格式
集合映射到 Hugo 内容目录
媒体文件保存到 static/images/uploads

TinaCMS 集成（不推荐）

⚠️ 请改用 Sveltia CMS。TinaCMS 对于 Hugo 有显著限制：

为何不使用 TinaCMS？

❌ 仅限 React 的可视化编辑 - Hugo 使用 Go 模板，可视化编辑无法工作 ❌ 复杂设置 - 需要 Node.js 服务器或 Tina Cloud ❌ 692 个 npm 包 - 对比 Sveltia 的 1 个 CDN 脚本 ❌ 7 个安全漏洞 - （截至 2025-11-04，4 个高危，3 个严重） ❌ 专注于 React/Next.js - Hugo 是次要用例 ❌ 仅限 YAML - 与 Sveltia 相同的限制，但没有好处

如果必须使用 TinaCMS

仅在以下情况下考虑 TinaCMS：

已经在使用 Tina Cloud
有 React 专业知识可用
需要 Tina 特定功能

参见捆绑的参考文档：references/tinacms-integration-guide.md（警告：不推荐）

Tailwind CSS v4 集成

Hugo 通过 Hugo Pipes 和 Tailwind CLI 支持 Tailwind CSS v4。这种方法与基于 Vite 的 React 项目有根本不同。

何时使用 Tailwind 对比主题

在 Hugo 中使用 Tailwind 当：

构建不依赖主题的自定义设计
需要实用优先的 CSS 工作流
想要完全的样式控制
相比 SCSS/Sass 更喜欢 Tailwind

使用主题（PaperMod、Book 等）当：

想要经过验证、生产就绪的设计
需要快速设置而无需自定义 CSS
对主题定制选项满意
不需要像素级完美的自定义设计

与 Vite + React 的关键区别

关键： 请不要尝试将 tailwind-v4-shadcn 技能模式用于 Hugo。该技能适用于 Vite + React 项目，与 Hugo 的资源管道不兼容。

方面	Vite + React	Hugo
构建系统	JavaScript (Node.js)	Go (Hugo 二进制文件)
Tailwind 集成	`@tailwindcss/vite` 插件	Tailwind CLI + PostCSS
配置文件	`vite.config.ts`	`hugo.yaml`
内容扫描	`content: []` 通配符	`hugo_stats.json`
开发服务器	Vite (端口 5173)	Hugo (端口 1313)
暗色模式	React ThemeProvider	CSS 类或 Alpine.js

快速开始（10分钟）

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

配置 Hugo (hugo.yaml)

build:
  writeStats: true  # 为 Tailwind 生成 hugo_stats.json

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

配置 Tailwind (tailwind.config.js)

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

配置 PostCSS (postcss.config.js)

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

创建 CSS 入口文件 (assets/css/main.css)

@import "tailwindcss";

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

在模板中处理 CSS (layouts/_default/baseof.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>

完整的 Tailwind v4 + Hugo 设置包括：

暗色模式实现（纯 CSS 和 Alpine.js）
Typography 插件设置
Forms 插件设置
模板集成模式
常见问题及解决方案
生产环境构建优化

参见捆绑资源：

参考指南：references/tailwind-v4-integration.md（综合文档）
最小模板：templates/hugo-tailwind-minimal/（起点）
博客模板：templates/hugo-tailwind-blog/（使用 Tailwind 的完整博客）

Tailwind 特定问题

在 Hugo 中使用 Tailwind 时的常见问题（所有问题及解决方案均在参考指南中记录）：

问题	原因	解决方案
CSS 未处理	PostCSS 未配置	在模板中验证 `resources.PostCSS`
类未清除	`hugo_stats.json` 未生成	在 `hugo.yaml` 中启用 `writeStats: true`
暗色模式损坏	配置错误	在 `tailwind.config.js` 中使用 `darkMode: 'class'`
资源指纹生成失败	Hugo Pipes 使用不正确	使用 `RelPermalink` 而非 `Permalink`
CSS 中的 Hugo 模板语法	无法在 CSS 中使用 `{{ }}`	在模板中应用类，而非 CSS
版本不匹配	CLI 与 PostCSS 插件	将所有更新到相同版本

模式 1：使用 PaperMod 主题的博客

# 脚手架
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

# 配置（见上面的 hugo.yaml 示例）

# 创建文章
hugo new content posts/first-post.md

# 开发
hugo server

# 构建
hugo --minify

何时使用：个人博客、公司博客、新闻网站

模式 2：使用 Hugo Book 的文档站点

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

# 为文档配置（嵌套导航、搜索）
# 参见：捆绑模板 `templates/hugo-docs/`

# 创建文档
hugo new content docs/getting-started/installation.md

# 构建
hugo --minify

何时使用：技术文档、知识库、API 文档

模式 3：落地页

# 脚手架
hugo new site landing --format yaml

# 使用自定义布局（无主题）
# 参见：捆绑模板 `templates/hugo-landing/`

# 单页结构
hugo new content _index.md

# 构建
hugo --minify

何时使用：营销网站、产品页面、作品集

模式 4：多语言站点

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

#

🇺🇸English

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.

# 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

# 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

The 7-Step Setup Process

Step 1: Installation and Verification

Install Hugo Extended using one of these methods:

Method 1: Homebrew (macOS/Linux) ✅ Recommended

brew install hugo

Method 2: Binary Download (Linux)

# 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

docker run --rm -it -v $(pwd):/src klakegg/hugo:ext-alpine

Method 4: NPM Wrapper (not recommended, may lag behind)

npm install -g hugo-bin

Verification:

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:

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 ✅

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

hugo mod init github.com/username/my-site

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

Add theme to hugo.yaml:

theme: "PaperMod"

When cloning project with submodules:

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):

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:

# 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):

---
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):

+++
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):

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

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

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

Manual deployment:

# Build site
hugo --minify

# Deploy to Workers
npx wrangler deploy

GitHub Actions (Automated):

Create .github/workflows/deploy.yml:

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 ✅ Addpublic/ to .gitignore - build output should not be committed ✅ Usedraft: 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 commitpublic/ directory - it's generated output, not source code ❌ Don't use different Hugo versions - local vs CI/CD version mismatch causes errors ❌ Don't forgetsubmodules: recursive - themes won't load in CI/CD ❌ Don't hardcode production URLs - use -b $CF_PAGES_URL or environment configs ❌ Don't pushresources/_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 (--- vs +++), 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)

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)

{
  "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)

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

<!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:

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 :

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`

Quick Start (10 Minutes)

Install Dependencies

npm install -D tailwindcss postcss autoprefixer

npx tailwindcss init

2. Configure Hugo (hugo.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

3. Configure Tailwind (tailwind.config.js)

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

4. Configure PostCSS (postcss.config.js)

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

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

@import "tailwindcss";

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

6. Process CSS in Template (layouts/_default/baseof.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>

7. Start Development

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`

Common Patterns

Pattern 1: Blog with PaperMod Theme

# 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

# 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

# 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

# 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

./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

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

check-versions.sh - Verify Hugo and tool versions

./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:

{{< 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:

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

Data Files

Use JSON/YAML/TOML data files:

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

Weekly Installs

Repository

jackspace/claudeskillz

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode77

gemini-cli76

codex73

cursor71

github-copilot65

claude-code62

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

122,000 周安装

Hugo 静态网站生成器完整指南：5分钟快速上手与7步设置流程

🇨🇳中文介绍

Hugo 静态网站生成器

快速开始（5分钟）

1. 安装 Hugo Extended 版本

2. 创建新的 Hugo 站点

相关 Skills

3. 配置和构建

7 步设置流程

步骤 1：安装和验证

步骤 2：项目脚手架

步骤 3：主题安装

步骤 4：配置

步骤 5：内容创建

步骤 6：构建和开发

步骤 7：Cloudflare Workers 部署

关键规则

始终要做

切勿做

已知问题预防

问题 #1：版本不匹配（Hugo 与 Hugo Extended）

问题 #2：baseURL 配置错误

问题 #3：TOML 与 YAML 配置混淆

问题 #4：Hugo 版本不匹配（本地与部署）

问题 #5：内容 Frontmatter 格式错误

问题 #6：主题未找到错误

问题 #7：日期时间扭曲问题

问题 #8：公共文件夹冲突

问题 #9：模块缓存问题

配置文件参考

hugo.yaml（完整生产环境示例）

wrangler.jsonc (Cloudflare Workers)

.gitignore（必需）

Sveltia CMS 集成（推荐）

为何为 Hugo 选择 Sveltia CMS？

设置（5分钟）

关键点：

TinaCMS 集成（不推荐）

为何不使用 TinaCMS？

如果必须使用 TinaCMS

Tailwind CSS v4 集成

何时使用 Tailwind 对比主题

与 Vite + React 的关键区别

快速开始（10分钟）

完整集成指南

Tailwind 特定问题

常见模式

模式 1：使用 PaperMod 主题的博客

模式 2：使用 Hugo Book 的文档站点

模式 3：落地页

模式 4：多语言站点

🇺🇸English

Hugo Static Site Generator

Quick Start (5 Minutes)

1. Install Hugo Extended

2. Create New Hugo Site

3. Configure and Build

The 7-Step Setup Process

Step 1: Installation and Verification

Step 2: Project Scaffolding

Step 3: Theme Installation

Step 4: Configuration

Step 5: Content Creation

Step 6: Build and Development

Step 7: Cloudflare Workers Deployment

Critical Rules

Always Do

Never Do

Known Issues Prevention

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

Issue #2: baseURL Configuration Errors

Issue #3: TOML vs YAML Configuration Confusion

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

Issue #5: Content Frontmatter Format Errors

Issue #6: Theme Not Found Errors

Issue #7: Date Time Warp Issues

Issue #8: Public Folder Conflicts

Issue #9: Module Cache Issues

Configuration Files Reference

hugo.yaml (Full Production Example)