hugo-theme

Hugo 主题开发

Hugo CMS 主题开发的中高级模式。根据任务加载相关参考文件。

参考文件

主题	最低 Hugo 版本	适用场景	文件
模板架构	v0.120+	需要设置带有区块的基础模板、了解模板查找顺序（kind/layout/type/section）、创建局部模板、使用局部模板装饰器（v0.154+），或了解 shortcode 基础知识	references/template-architecture.md
资源管线	v0.161+	需要集成 Tailwind CSS v4（css.TailwindCSS）或 v3（PostCSS）、使用 Hugo Pipes 打包 SCSS/JS、设置指纹和 SRI、使用 srcset 构建响应式图片，或处理页面/全局/远程资源	references/asset-pipeline.md
Shortcode 与渲染钩子	v0.112+	需要复杂的嵌套 shortcode、原始 HTML shortcode、在 shortcode 中渲染 Markdown、用于链接/图片/标题/代码块的自定义渲染钩子，或特定语言的代码块渲染（Mermaid 等）	references/shortcodes-and-hooks.md
内容组织与 i18n	v0.126+	需要处理叶子与分支 bundle、无头 bundle、封面图片、自定义分类法、内容适配器（v0.126+，动态页面）、特定 section 的布局、原型，或国际化（翻译表、多语言）	references/content-and-i18n.md
封面图片	v0.120+	需要为文章添加封面/主视觉图片、同时支持页面 bundle 资源和 frontmatter 路径、生成响应式 srcset，或妥善处理无封面图片的情况	references/cover-images.md
模块与性能	v0.109+	需要使用 Hugo Modules（init、import、vendor、workspace）、通过 mount 配置构建主题组件、使用 partialCached 优化构建速度、配置缓存 TTL，或使用由配置驱动的主题（params、cascade）	references/modules-and-performance.md
设计、用户体验与无障碍访问	v0.120+	需要排版系统、无障碍配色方案、设计令牌、语义化 HTML 地标、ARIA 模式、键盘导航、无障碍表单、内容优先布局、响应式导航、互动模式（阅读进度、深色模式切换、分享）、Core Web Vitals 优化、容器查询、:has() 选择器，或测试/QA 自动化（axe-core、Lighthouse CI、视觉回归）	references/design-accessibility.md
SEO、输出格式与 CI/CD	v0.120+	需要 JSON-LD 结构化数据、Open Graph / Twitter Cards、自定义输出格式（JSON、AMP）、自定义站点地图，或主题的 CI/CD 管线（GitHub Actions、测试、部署）	references/seo-outputs-testing.md

快速入门

{{/* Minimal theme baseof.html — start here */}}
<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ block "title" . }}{{ .Site.Title }}{{ end }}</title>
  {{ block "styles" . }}{{ end }}
</head>
<body>
  {{ block "header" . }}{{ partial "header.html" . }}{{ end }}
  <main>{{ block "main" . }}{{ end }}</main>
  {{ block "footer" . }}{{ partial "footer.html" . }}{{ end }}
  {{ block "scripts" . }}{{ end }}
</body>
</html>

分步指南：初始化新主题

# 1. Create the theme directory
mkdir -p themes/my-theme/{layouts/{_default,_markup,partials,shortcodes},assets/{scss,css,js}}

# 2. Create baseof.html (use the template above) defining blocks:
#    title, styles, header, main, footer, scripts

# 3. Create partials for reusable components
#    layouts/partials/header.html, footer.html, css.html

# 4. Set up your asset pipeline
#    - SCSS  → assets/scss/main.scss + toCSS partial
#    - Tailwind  → assets/css/main.css + css.TailwindCSS partial
#    - JS  → assets/js/main.js + js.Build

# 5. Configure hugo.yaml
#    theme: my-theme
#    See the reference file for your chosen CSS approach.

# 6. Build and verify
hugo --gc
ls public/ | head

**提示：**项目级 layouts/ 会覆盖主题的 layouts/。如果想单独测试主题，在需要覆盖之前，请保持项目的 layouts/ 目录为空。

常见陷阱

• SCSS 需要 Hugo extended 版本。 macOS/Homebrew 默认安装的 Hugo 构建版本并非 extended 版本。使用 hugo version | grep extended 验证。
• Tailwind v4 使用 css.TailwindCSS，而非 PostCSS。 对于 v4，不要安装 postcss-cli，请直接使用原生管道。Tailwind v3 仍需要 PostCSS 管道。
• partialCached 使用非常量参数时会产生过时缓存。 变体字符串（.Section、page.RelPermalink）必须在每次调用时唯一。重复的分区名称会导致结果过时。
• hugo new 遵循 archetype 目录结构。 将 archetype 放在 archetypes/<section>/index.md，即可创建页面包，而非扁平文件。
• resources.Get 会查找 assets/，而非 static/。 static/ 中的文件会原样复制，不会由 Hugo Pipes 处理。凡是需要通过 Pipes 处理的文件，都应放在 assets/ 中。
• 内容适配器模板必须使用 _content.gotmpl 命名。 同一目录中存在 _content.gotmpl 时，普通的 .md 文件会被忽略。
• 渲染钩子模板应放在 _markup/ 子目录中。 不要直接放在 _default/ 中；它们需要位于 layouts/_default/_markup/render-link.html 或特定分区的 layouts/<type>/_markup/ 中。
• partial 中的 block 会与页面模板中的 define 冲突。 partial（例如 head.html）中的 {{ block "title" . }} 与页面模板（例如 single.html）中的 {{ define "title" }} 使用相同的 Go 模板命名空间。当两者都存在于渲染树中时，Hugo 会报错：multiple definition of template "title"。解决方法：在 partial 中使用直接的页面变量（.Title、.Site.Title），而非 block。block 仅用于 baseof.html 外壳。