模板 on Hugo 中文文档

404 页面

Thu, 01 Oct 2026 00:00:00 +0800

自定义 404 页面

在站点根目录输出一个 404 错误页面，需要在 layouts 目录的根下创建 404 模板。注意它与普通页面模板的位置不同：单页模板、列表模板都放在子目录中（或者按 Hugo 的模板查找规则层层向上查找），而 404 模板只认 layouts 根目录，放在别处不会被采用。

robots.txt

Thu, 01 Oct 2026 00:00:00 +0800

启用 robots.txt 生成

要让 Hugo 从模板生成 robots.txt，先修改项目配置：

hugo.toml

enableRobotsTXT = true

开启之后，Hugo 会在站点根目录输出 robots.txt，默认内容来自内建模板，只有一行：

站点地图

Thu, 01 Oct 2026 00:00:00 +0800

概览

Hugo 内建的站点地图模板符合 sitemap 协议 v0.9 版。

单语言项目中，Hugo 使用内建的 sitemap 模板，在 publishDir 根目录生成一个 sitemap.xml。

多语言项目则会生成两份内容：

在每种语言（每个站点）的根目录下，使用内建的 sitemap 模板生成各自语言的 sitemap.xml；
在 publishDir 根目录下，使用内建的 sitemapindex 模板生成一个索引文件 sitemapindex.xml，把各语言的地图汇总起来。

配置

站点地图的默认行为可在项目配置的 [sitemap] 小节中调整，可用的键包括：

RSS 订阅

Thu, 01 Oct 2026 00:00:00 +0800

配置

默认情况下，构建项目时 Hugo 会为**首页、section、分类法（taxonomy）与分类法条目（term）**页面生成 RSS 订阅源。生成范围由项目配置中的 [outputs] 决定。例如，只为首页和 section 页面生成，而不为分类法与条目页面生成：

菜单模板

Thu, 01 Oct 2026 00:00:00 +0800

概览

先定义菜单项，再用菜单方法渲染菜单。Hugo 在 site.Menus 上暴露所有菜单，例如 site.Menus.main、site.Menus.footer。

决定渲染方式的因素有三个：

菜单项的定义方式：自动生成、写在前置元数据中、写在项目配置中；
菜单结构：平铺还是嵌套；
菜单项的本地化方式：项目配置或翻译表。

下面的示例把这些组合都考虑在内。

分页

Thu, 01 Oct 2026 00:00:00 +0800

为什么需要分页

在列表页上一次性展示大量页面集合并不友好：

超长列表令人生畏且难以浏览，访客容易在海量信息中迷失；
页面越大加载越慢，可能让人失去耐心而离开站点；
没有任何筛选或组织时，找到一个特定条目变成了漫长的滚动。

对 home、section、taxonomy、term 这几类列表页进行分页可以改善可用性。

内建模板

Thu, 01 Oct 2026 00:00:00 +0800

内建模板清单

Hugo 为常见需求内置了一批模板，无需自己编写即可直接调用。按调用方式可以把它们分为两类。

内建局部模板放在 _internal/ 下，用 partial 函数调用：

内建模板	用途
`_internal/disqus.html`	Disqus 评论组件
`_internal/google_analytics.html`	Google Analytics 4
`_internal/opengraph.html`	Open Graph 协议元数据
`_internal/pagination.html`	pager 之间的分页导航
`_internal/schema.html`	microdata 结构化数据
`_internal/twitter_cards.html`	X（Twitter）卡片元数据

内建的输出模板用于生成整份文件，它们同样位于 Hugo 的内建模板命名空间中，例如 RSS 的 _internal/rss.xml、站点地图的 _internal/sitemap.xml 与多语言索引的 _internal/sitemapindex.xml。这类模板不需要在页面模板中调用，Hugo 在生成对应输出格式时自动使用。

简介

Thu, 01 Oct 2026 00:00:00 +0800

模板是什么

模板用变量、函数与方法把内容、资源与数据转换为发布出去的页面。Hugo 使用 Go 的 text/template 与 html/template 包：前者生成文本输出，后者生成对代码注入安全的 HTML 输出。渲染 HTML 文件时，Hugo 默认使用 html/template。下面这个模板初始化两个变量，并在段落中显示它们的乘积：

模板查找顺序

Thu, 01 Oct 2026 00:00:00 +0800

查找规则

Hugo 为给定页面选择模板时，会考虑下列参数，并按具体程度给模板排序。这套顺序应当让人感到自然，具体取值差异见后文示例。

新版模板系统概览

Thu, 01 Oct 2026 00:00:00 +0800

在 Hugo v0.146.0 中，Hugo 完全重新实现了 Go 模板的处理方式，包括 layouts 目录的结构调整与更强大的模板查找系统。为了尽量保持向后兼容，官方按「旧到新」做了映射，但仍有一些已知的破坏性变化。本文汇总其中最重要的部分。

局部模板装饰器

Thu, 01 Oct 2026 00:00:00 +0800

概述

局部模板装饰器（partial decorator）把两个文件连接起来：调用方模板提供一段代码，装饰器决定这段代码出现在哪里。这样局部模板就能包住内容，而不必知道被包裹块的标记结构或内部逻辑。

短代码模板

Thu, 01 Oct 2026 00:00:00 +0800

简介

Hugo 为许多常见任务提供了内置短代码，但更专门的需求往往需要自己编写。常见的自定义短代码包括音频播放器、视频播放器、图片画廊、图表、地图、表格，以及各种自定义元素。

内容类型

Thu, 01 Oct 2026 00:00:00 +0800

模板目录与查找依据

Hugo 在站点根目录的 layouts/ 目录中查找模板。虽然多数站点用不到全部模板，但一个中等复杂度的站点通常长这样：

layouts/
├── _markup/
│   ├── render-image.html
│   └── render-link.html
├── _partials/
│   ├── footer.html
│   └── header.html
├── _shortcodes/
│   └── audio.html
├── books/
│   ├── page.html
│   └── section.html
├── baseof.html
├── home.html
├── page.html
├── section.html
├── taxonomy.html
└── term.html

具体用哪个模板由查找顺序（lookup order）决定，判定时综合模板类型（template type）、页面种类（page kind）、内容类型（content type）、section（内容区块）、语言与输出格式。要为某类页面写出可预期的模板，就必须先理解这套顺序。