模板

概述

参考：
官网文档，模板

Hugo 为了将 Content 添加到 Layout 中，将所有的 Content 抽象为如下几种类型的 Page：

Home Page(主页) # $Kind 值为 home。
Regular Pages(常规页) # $Kind 值为 page。
Section Pages(部分页) # $Kind 值为 section。
Taxonomy Pages # $Kind 值为 taxonomy。
Term Pages # $Kind 值为 term。

Hugo 将模板分为如下几种类型：

Base Templates(基本模板)
List Templates
Homepage Templates
Section Templates(部分模板)
Taxonomy Templates
Single Page Templates
Content View Templates
Data Templates
Partial Templates
Shortcode Templates
Local File Templates
Menu Templates
RSS Templates
Internal Templates
404 Page
Pagination(分页)
Template Debugging

Hugo 的每种模板都可以渲染一种或多种类型的页面。在开始准备渲染页面时，首先要确定页面的 Kind 变量的值，即.确定页面的类型。比如 section 类型的页面

渲染页面时查找模板的顺序

参考：
官方文档，模板-查找顺序

Hugo 基于 Content 决定要使用的 Template。从 content/ 目录下逐一处理每个内容(i.e. Page(页面))，从 layouts/ 目录中为每个内容选择要使用的布局(i.e. 模板)。

一个 Content 的 Page 类型可以通过 $Kind 变量查看，每种类型的 Page 都会匹配不同的模板文件，并且会在 layouts/ 目录下根据规则逐一查找模板文件，并使用找到的第一个文件与基本模板文件(baseof.html)一起将内容根据模板布局渲染成可供浏览的页面，然后转译成静态站点文件，保存到 public/ 目录下。

基本模板的查找顺序

每种 Page 所使用的模板都要与基本模板组合在一起，共同将内容渲染成页面。所以在查找下面的模板之前，都要先按照如下顺序查找基本模板

这里用 content/posts/ 目录下的所有 Content 举例，这些 Content 将会按照如下顺序逐一查找基本模板文件：

layouts/posts/baseof.html
……
layouts/_default/baseof.html

layouts/_default/baseof.html 这个基本模板相当于是所有页面的后盾，任何找不到模板的页面，最后都会使用该模板，这算是一个万金油的位置。

Home Page 的模板查找顺序

Hugo 在渲染主页时，就算没有任何 content/，Hugo 也会自动去寻找适用于 Home Page 的模板，只需要在 layous/ 下创建一个 index.html 文件即可，此时访问 / 就不会显示 Hugo 基本使用示例中的 Page Not Found，而是一个空白的页面，这是因为在 index.html 中没有任何布局，并且也没有任何 Content 根据布局被渲染成页面。

Section Pages 的模板查找顺序

https://gohugo.io/templates/lookup-order/#examples-layout-lookup-for-section-pages

Section Pages 通常都是在每个目录下的 _index.md 文件。

Hugo 首先在 layouts/ 目录中查找 _index.md 文件所在目录的同名目录下的同名 .html 文件。
然后从 _default/ 目录查找匹配目标
根据页面类型匹配

举个例子：现在想要渲染 content/posts/_index.md 页面，那就按照如下顺序逐一查找模板文件

layouts/posts/posts.html
layouts/posts/section.html
layouts/posts/list.html
……

后续还有很多要查找的文件，在笔记就不再一一列出，可以直接去官网查看。这里只是总结出大体规律。

Regular Pages 的模板查找顺序

Regular Pages 通常是指每个 Content，比如 content/posts/my_first_post.md 就是一个常规的页面，Hugo 将会按照如下顺序逐一为该文件查找模板文件

layouts/posts/single.html
layouts/_default_/single.html

Taxonomy Pages 的模板查找顺序

Term Pages 的模板查找顺序

Block

Hugo 可以基于 Block(块) 将多个模板组合起来一同渲染，通常基于 block、define 关键字。在内层模板中使用 define 关键字定义块，然后在外层模板中使用 block 引用定义的块

比如现在有模板 A.html，其中定义一个名为 main 的块。

{{ define "main" }}
<p>在这里定义了名为 main 的</p>
{{ end }}

在模板 B.html 中，引用名为 main 的块。

<body>
    {{ block "main" . }}{{ end }}
</body>

最后渲染出来的效果就像这样：

<body>
    <p>在这里定义了名为 main 的</p>
</body>

基本模板

基本模板通常名称为 baseof.html，通常作为网站所有页面的外壳使用，以便让页面具有统一的风格，通常来说，一个基本模板是这样的：

{{/* 这是一个基本模板，用来作为网站的外壳，以便让网站保持相同的风格 */}}
<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <title>
        {{ block "title" . }}
        {{ .Site.Title }}
        {{ end }}
    </title>
</head>

<body>
    <!-- 引用其他模板中定义的名为 main 的块 -->
    {{ block "main" . }}{{ end }}

    <!-- 引用其他模板中定义的名为 footer 的块 -->
    {{ block "footer" . }}{{ end }}
</body>

</html>

列表模板

https://gohugo.io/templates/lists/

列表模板在 Hugo 中是很特别的，是用于在单个 HTML 页面中呈现多跳内容的模板，绝大部分类型的 Page 通常都可以使用 list.html 作为其渲染模板。

部分模板

反馈

此页是否对你有帮助？

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

最后修改 March 25, 2025: clearup (feb59d93)