模板

• 1: Hugo模板入门介绍
• 2: Hugo 的查找顺序
• 3: 自定义输出格式
• 4: 基础模板和块
• 5: Markdown渲染钩子
• 6: 在Hugo中的内容列表
• 7: 主页模板
• 8: 分类法（Taxonomy）模板
• 9: 章节页面模板
• 10: 单页模板
• 11: 内容视图模板
• 12: 数据模板
• 13: 局部模板
• 14: 创建自己的简码
• 15: 本地文件模板
• 16: 自定义404页面
• 17: 菜单模板
• 18: 分页
• 19: RSS模板
• 20: Sitemap模板
• 21: Robots.txt
• 22: 内置模板
• 23: 模板调试

1 - Hugo模板入门介绍

Introduction to Hugo Templating - Hugo模板入门介绍

https://gohugo.io/templates/introduction/

​ Hugo 使用 Go 的 html/template 和 text/template 库作为模板的基础。

​ 以下仅为 Go 模板的入门指南。若想深入了解 Go 模板，请查看官方 Go 文档。

​ Go 模板提供了一种极其简单的模板语言，坚信只有最基本的逻辑应该放在模板或视图层中。

基本语法

​ Go 模板是 HTML 文件，并加入了变量和函数。Go 模板的变量和函数可以在 {{ }}中进行访问。

访问预定义变量

​ 预定义变量可以是当前作用域中已经存在的变量（如下面变量章节的.Title示例），也可以是自定义变量（如该章节中的$address示例）。

1
2

{{ .Title }}
{{ $address }}

​ 函数的参数使用空格分隔。通常的语法如下：

1

{{ FUNCTION ARG1 ARG2 .. }}

​ 下面的示例使用1和2作为add函数的输入：

1

{{ add 1 2 }}

通过点符号访问方法和字段

​ 访问在内容前置元数据中定义的 Page 参数中的 bar。

1

{{ .Params.bar }}

括号可以用来分组项

1

{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}

单个语句可以分成多行

1
2
3
4

{{ if or
  (isset .Params "alt")
  (isset .Params "caption")
}}

原始字符串字面值可以包含换行符

1
2

{{ $msg := `Line one.
Line two.` }}

变量

​ 每个Go模板都有一个数据对象。在Hugo中，每个模板都传递了一个Page。在下面的示例中，.Title是Page变量中可访问的元素之一。

​ 由于Page是模板的默认作用域，因此可以通过点前缀(.Title)轻松访问当前作用域(. —— “the dot")中的Title元素：

1

<title>{{ .Title }}</title>

​ 值也可以存储在自定义变量中，并在之后被引用：

​ 自定义变量需要以$为前缀。

1
2

{{ $address := "123 Main St." }}
{{ $address }}

​ 使用=运算符可以重新定义变量。下面的示例在主页上打印"Var is Hugo Home”，在其他所有页面上打印"Var is Hugo Page"：

1
2
3
4
5

{{ $var := "Hugo Page" }}
{{ if .IsHome }}
    {{ $var = "Hugo Home" }}
{{ end }}
Var is {{ $var }}

函数

​ Go模板仅提供了一些基本函数，但还提供了一种机制，使应用程序能够扩展原始函数集。

​ Hugo模板函数提供了特定于构建站点的附加功能。通过使用函数名和由空格分隔的所需参数来调用函数。如果没有重新编译Hugo，则无法添加模板函数。

示例1：添加数字

1
2

{{ add 1 2 }}
<!-- prints 3 -->

示例2：比较数字

1
2

{{ lt 1 2 }}
<!-- prints true (i.e., since 1 is less than 2) -->

​ 请注意，这两个示例都使用了Go模板的math函数。

​ 在Go模板文档中，有比Hugo文档中列出的更多的布尔运算符。

Includes

​ 在包含（Include）另一个模板时，您需要传递它需要访问的数据。

​ 为了传递当前上下文，请记住包含一个尾随点。

​ 模板位置始终从Hugo的layouts/目录开始。

Partial

​ partial函数用于使用语法{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}包含部分（partial）模板。

​ 包含layouts/partials/header.html部分（partial）模板的示例：

1

{{ partial "header.html" . }}

模板

​ 在早期版本的Hugo中，template函数用于包含部分（partial）模板。现在，它仅用于调用内部模板。语法为{{ template "_internal/<TEMPLATE>.<EXTENSION>" . }}。

​ 可以在这里找到可用的内部模板。

​ 包含内部opengraph.html模板的示例：

1

{{ template "_internal/opengraph.html" . }}

逻辑

​ Go模板提供了最基本的迭代和条件逻辑。

迭代

​ Go模板大量使用range来迭代map、array或slice。以下是如何使用range的不同示例。

示例1：使用上下文(.)

1
2
3

{{ range $array }}
    {{ . }} <!-- The . represents an element in $array -->
{{ end }}

示例2：为数组元素的值声明变量名

1
2
3

{{ range $elem_val := $array }}
    {{ $elem_val }}
{{ end }}

示例3：为数组元素的索引和值声明变量名

​ 对于数组或切片，第一个声明的变量将映射到每个元素的索引。

1
2
3

{{ range $elem_index, $elem_val := $array }}
   {{ $elem_index }} -- {{ $elem_val }}
{{ end }}

示例4：为map元素的键和值声明变量名

​ 对于map，第一个声明的变量将映射到每个map元素的键。

1
2
3

{{ range $elem_key, $elem_val := $map }}
   {{ $elem_key }} -- {{ $elem_val }}
{{ end }}

示例5：针对空map、数组或切片的条件语句

​ 如果传递给range的map、数组或切片长度为零，则将执行else语句。

1
2
3
4
5

{{ range $array }}
    {{ . }}
{{ else }}
    <!-- This is only evaluated if $array is empty -->
{{ end }}

条件语句

​ if、else、with、or、and和not提供了处理Go模板中条件逻辑的框架。与range一样，if和with语句也是用{{ end }}关闭的。

​ Go 模板将以下值视为false：

• false (boolean)
• 0 (integer)
• 任何长度为零的数组、切片、映射或字符串

示例1：with

​ 通常使用with编写"if something exists, do this"这样的语句。

​ with会在其作用域内重新绑定上下文(.)（就像在range中一样）。

​ 如果变量不存在，或者如果它按上面所述计算为"false"，则它会跳过该块。

1
2
3

{{ with .Params.title }}
    <h4>{{ . }}</h4>
{{ end }}

示例2：with..else

​ 下面的代码片段如果设置了"description"前置元数据的值，则使用它，否则使用默认的.Summary页面变量：

1
2
3
4
5

{{ with .Param "description" }}
    {{ . }}
{{ else }}
    {{ .Summary }}
{{ end }}

​ 参见.Param函数。

示例3：if

​ 编写with的另一种替代（更冗长）方法是使用if。在这里，.不会重新绑定。

​ 下面的示例是使用if重写的"示例1"：

1
2
3

{{ if isset .Params "title" }}
    <h4>{{ index .Params "title" }}</h4>
{{ end }}

示例4：if..else

​ 下面的示例是使用if .. else重写的"示例2"，并使用isset函数+ .Params变量（不同于.Param函数）：

1
2
3
4
5

{{ if (isset .Params "description") }}
    {{ index .Params "description" }}
{{ else }}
    {{ .Summary }}
{{ end }}

示例5： if .. else if .. else

​ 与with不同，if还可以包含else if子句。

1
2
3
4
5
6
7

{{ if (isset .Params "description") }}
    {{ index .Params "description" }}
{{ else if (isset .Params "summary") }}
    {{ index .Params "summary" }}
{{ else }}
    {{ .Summary }}
{{ end }}

示例6： and & or

1

{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}

管道

​ Go模板最强大的组件之一是能够将操作一层层堆叠在一起。这是通过使用管道来完成的。从Unix管道借鉴而来，概念很简单：每个管道的输出都成为下一个管道的输入。

​ 由于Go模板的语法非常简单，因此管道对于能够链接在一起的函数调用非常重要。管道的一个限制是它们只能处理单个值，该值成为下一个管道的最后一个参数。

​ 一些简单的示例应该有助于帮助您了解如何使用管道。

示例1： shuffle

​ 以下两个示例在功能上是相同的：

1
2

{{ shuffle (seq 1 5) }}
{{ (seq 1 5) | shuffle }}

示例2： index

​ 以下访问名为"disqus_url"的页面参数并转义HTML。此示例还使用内置于Go模板中的index函数：

1

{{ index .Params "disqus_url" | html }}

示例3： 带有isset的or

1
2
3

{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
Stuff Here
{{ end }}

可以重写为

1
2
3

{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
Stuff Here
{{ end }}

上下文（也称"点"）

​ Go模板最容易被忽视的理解概念是，{{ . }}始终指向当前上下文。

• 在您的模板的顶层，它将是可用的数据集。
• 但是，在迭代中，它将具有循环中当前项的值；即{{ . }}将不再引用整个页面可用的数据。

​ 如果您需要从循环内部访问页面级别的数据（例如，在前置元数据中设置的页面参数），则可能需要执行以下操作之一：

1.定义一个独立于上下文的变量

​ 以下示例演示如何定义一个独立于上下文的变量。

tags-range-with-page-variable.html

1
2
3
4
5
6
7
8
9

{{ $title := .Site.Title }}
<ul>
{{ range .Params.tags }}
    <li>
        <a href="/tags/{{ . | urlize }}">{{ . }}</a>
        - {{ $title }}
    </li>
{{ end }}
</ul>

请注意，一旦我们进入循环（即 range），{{ . }} 的值就已经改变了。我们在循环外面定义了一个变量（{{ $title }}），并为其分配了一个值，以便我们可以从循环内部访问该值。

2.使用$.访问全局上下文

​ $ 在模板中具有特殊意义。$默认情况下被设置为 .（“the dot”）的起始值。这是Go text/template的文档功能。这意味着您可以从任何地方访问全局上下文。下面是先前的代码块的等效示例，但现在使用 $ 从全局上下文中获取 .Site.Title：

range-through-tags-w-global.html

1
2
3
4
5
6
7
8

<ul>
{{ range .Params.tags }}
  <li>
    <a href="/tags/{{ . | urlize }}">{{ . }}</a>
            - {{ $.Site.Title }}
  </li>
{{ end }}
</ul>

​ 如果有人恶意重新定义特殊字符（例如 {{ $ := .Site }}），$ 的内置魔力将停止工作。不要这样做。当然，您可以在全局上下文中使用 {{ $ := . }} 来重置 $ 的默认值以恢复其功能。

空格

​ Go 1.6可以通过在相应的 {{或}}分隔符旁边包含连字符（-）和空格来修剪Go标记的两侧的空格的功能。

​ 例如，以下Go模板将在其HTML输出中包含换行符和水平制表符：

1
2
3

<div>
  {{ .Title }}
</div>

它将输出：

1
2
3

<div>
  Hello, World!
</div>

​ 在以下示例中使用-将删除围绕.Title变量的额外空格并删除换行符：

1
2
3

<div>
  {{- .Title -}}
</div>

它将输出：

1

<div>Hello, World!</div>

Go 语言认为以下字符是空白字符：

• 空格
• 水平制表符
• 回车符
• 换行符

注释

​ 为了使您的模板组织有序并在团队之间共享信息，您可能希望向您的模板添加注释。在Hugo中有两种方法可以做到这一点。

Go模板注释

​ Go模板支持{{/*和*/}}来打开和关闭注释块。该块内的任何内容都不会被渲染。

例如：

1

Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.

将渲染Bonsoir, Eliott.，而不关心注释块中的语法错误（add 0 + 2）。

HTML 注释

​ 您可以通过将 HTML 代码注释的字符串管道化到 safeHTML 中来添加 HTML 注释。

例如：

1

{{ "<!-- This is an HTML comment -->" | safeHTML }}

​ 如果您需要使用变量构造这样的HTML注释，只需将printf管道化到safeHTML。

例如：

1

{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}

包含 Go 模板的 HTML 注释

​ 默认情况下，HTML注释会被删除，但其内容仍将被求值。这意味着尽管HTML注释永远不会将任何内容渲染到最终的HTML页面，但其中包含的代码可能会导致构建过程失败。

​ 不要尝试使用HTML注释来注释掉Go模板代码。

1
2

<!-- {{ $author := "Emma Goldman" }} was a great woman. -->
{{ $author }}

​ 模板引擎将删除HTML注释中的内容，但如果其中存在Go模板代码，则将首先求值任何Go模板代码。因此，上面的示例将渲染成Emma Goldman，因为$author变量在HTML注释中得到求值。但是，如果HTML注释中的代码有错误，构建将会失败。

Hugo参数

​ Hugo 提供了通过站点配置（用于整个站点的值）或每个特定内容的元数据（即前置元数据）向模板层传递值的选项。您可以定义任何类型的任何值，并在模板中任意使用它们，只要这些值得到前置元数据格式支持。

使用内容（page）参数

​ 您可以在单个内容的前置元数据中提供变量以供模板使用。

​ Hugo 文档中使用了一个示例。大多数页面都受益于提供目录，但有时目录并不合适。我们在前置元数据中定义了一个 notoc 变量，当设置为 true 时，将防止目录呈现。

以下是示例前置元数据：

content/example.md

=== “yaml”

``` yaml
---
notoc: true
title: Example
---
```

=== “toml”

``` toml
+++
notoc = true
title = 'Example'
+++
```

=== “json”

``` json
{
   "notoc": true,
   "title": "Example"
}
```

​ 以下是可以在 toc.html 局部模板中使用的对应代码示例：

layouts/partials/toc.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{ if not .Params.notoc }}
<aside>
  <header>
    <a href="#{{ .Title | urlize }}">
    <h3>{{ .Title }}</h3>
    </a>
  </header>
  {{ .TableOfContents }}
</aside>
<a href="#" id="toc-toggle"></a>
{{ end }}

​ 我们希望页面的默认行为是包含目录，除非另有指定。此模板检查此页面前置元数据中的 notoc: 字段是否为 true。

使用站点配置参数

​ 您可以在站点配置文件中任意定义任何数量的站点级参数。这些参数在您的模板中全局可用。

​ 例如，您可以声明以下内容：

config.

=== “yaml”

``` yaml
params:
  copyrighthtml: Copyright © 2017 John Doe. All Rights Reserved.
  sidebarrecentlimit: 5
  twitteruser: spf13
```

=== “toml”

``` toml
[params]
  copyrighthtml = 'Copyright © 2017 John Doe. All Rights Reserved.'
  sidebarrecentlimit = 5
  twitteruser = 'spf13'
```

=== “json”

``` json
{
   "params": {
      "copyrighthtml": "Copyright \u0026#xA9; 2017 John Doe. All Rights Reserved.",
      "sidebarrecentlimit": 5,
      "twitteruser": "spf13"
   }
}
```

​ 在页脚布局中，您可以声明仅在提供了 copyrighthtml 参数时才呈现的 <footer>。如果提供了该参数，则需要通过 safeHTML 函数声明该字符串可以安全使用，以便 HTML 实体不会被再次转义。这使您可以轻松地每年 1 月 1 日仅更新顶级配置文件，而无需在模板中查找。

1
2
3
4
5

{{ if .Site.Params.copyrighthtml }}
    <footer>
        <div class="text-center">{{ .Site.Params.CopyrightHTML | safeHTML }}</div>
    </footer>
{{ end }}

​ 一种替代写"if“并引用同一值的方法是使用with。with在其作用域内重新绑定上下文(.)，如果该变量不存在，则跳过块：

layouts/partials/twitter.html

1
2
3
4
5
6

{{ with .Site.Params.twitteruser }}
    <div>
        <a href="https://twitter.com/{{ . }}" rel="author">
        <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{ . }}" alt="Twitter"></a>
    </div>
{{ end }}

​ 最后，您也可以将"魔术常量"从您的布局中拉出来。以下示例使用first函数，以及.RelPermalink页面变量和.Site.Pages站点变量。

1
2
3
4
5
6
7
8

<nav>
  <h1>Recent Posts</h1>
  <ul>
  {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
  {{- end -}}
  </ul>
</nav>    

示例：显示未来事件

​ 假设有以下内容结构和前置元数据：

1
2
3
4
5

content/
└── events/
    ├── event-1.md
    ├── event-2.md
    └── event-3.md

content/events/event-1.md.

=== “yaml”

``` yaml
date: 2021-12-06T10:37:16-08:00
draft: false
end_date: 2021-12-05T11:00:00-08:00
start_date: 2021-12-05T09:00:00-08:00
title: Event 1
```

=== “toml”

``` toml
date = 2021-12-06T10:37:16-08:00
draft = false
end_date = 2021-12-05T11:00:00-08:00
start_date = 2021-12-05T09:00:00-08:00
title = 'Event 1'
```

=== “json”

``` json
{
   "date": "2021-12-06T10:37:16-08:00",
   "draft": false,
   "end_date": "2021-12-05T11:00:00-08:00",
   "start_date": "2021-12-05T09:00:00-08:00",
   "title": "Event 1"
}
```

​ 这个局部模板渲染未来的事件：

layouts/partials/future-events.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<h2>Future Events</h2>
<ul>
  {{ range where site.RegularPages "Type" "events" }}
    {{ if gt (.Params.start_date | time.AsTime) now }}
      {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
      <li>
        <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
      </li>
    {{ end }}
  {{ end }}
</ul>

​ 如果将前置元数据限制为TOML格式，并省略日期字段周围的引号，则可以执行日期比较而无需强制转换。

layouts/partials/future-events.html

1
2
3
4
5
6
7
8
9

<h2>Future Events</h2>
<ul>
  {{ range where (where site.RegularPages "Type" "events") "Params.start_date" "gt" now }}
    {{ $startDate := .Params.start_date | time.Format ":date_medium" }}
    <li>
      <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ $startDate }}
    </li>
  {{ end }}
</ul>

另请参阅

• 文件变量
• 菜单变量

2 - Hugo 的查找顺序

Hugo’s Lookup Order - Hugo 的查找顺序

https://gohugo.io/templates/lookup-order/

​ Hugo按照一定的顺序查找给定页面的布局，从最具体的布局开始。

Hugo 布局查找规则

​ Hugo在选择给定页面的布局时会考虑下面列出的参数。它们按优先级排序。这应该很自然，但具体的参数变化请参考下面的表格。

• Kind

  页面的Kind（主页是其中之一）。请参见下面每个种类的示例表格。这也确定了它是单页面（即常规内容页面。然后我们在_default/single.html中寻找HTML模板）还是列表页面（章节列表、主页、分类列表、分类术语。然后我们在_default/list.html中寻找HTML模板）。

• Layout

  可以在页面前置元数据中设置。

• 输出格式

  请参见自定义输出格式。输出格式既有一个name（例如rss、amp、html），也有一个suffix（例如xml、html）。我们更喜欢两者匹配（例如index.amp.html），但寻找较不具体的模板。

请注意，如果输出格式的媒体类型定义了多个后缀，则只考虑第一个后缀。

• Language

  模板名称中会考虑语言代码。如果站点语言是fr，则index.fr.amp.html将优于index.amp.html，但 index.amp.html 将在 index.fr.html 之前被选择。

• Type

  如果在前置元数据中设置了type的值，则它是type的值，否则它是根章节的名称（例如"blog"）。它总是有一个值，所以如果未设置，则值为"page"。

• Section

  对于section、taxonomy和term类型很重要。

提示：下面的示例看起来很长、很复杂。这就是灵活性在起作用。大多数Hugo站点只包含少量模板：

1 2 3 4 5

├── _default │ ├── baseof.html │ ├── list.html │ └── single.html └── index.html

带有主题的 Hugo 布局查找规则

​ 在Hugo中，布局可以存在于项目或主题的布局文件夹中，并且会选择最具体的布局。Hugo将交错查找下面的布局，找到最具体的一个布局，无论是在项目还是主题中。

示例：常规页面的布局查找

示例：主页的布局查找

示例：章节页面的布局查找

示例：分类页面的布局查找

示例：术语页面的布局查找

另请参阅

• 创建自己的简码
• RSS 模板
• 章节页面模板
• 单页面模板
• 站点地图模板

3 - 自定义输出格式

Custom Output Formats - 自定义输出格式

https://gohugo.io/templates/output-formats/

​ Hugo可以将内容输出为多种格式，包括日历事件、电子书格式、Google AMP和JSON搜索索引，或任何自定义文本格式。

​ 本页介绍了如何正确配置站点的媒体类型和输出格式，以及如何为自定义输出创建模板。

媒体类型

​ 媒体类型（也称为MIME类型和内容类型）是用于在互联网上传输文件格式和格式内容的两部分标识符。

​ 这是Hugo中的完整内置媒体类型集：

注意：

• 可以添加自定义媒体类型或更改默认值；例如，如果您想将text/html的后缀更改为asp。
• Suffixes是在Hugo中用于该媒体类型的URL和文件名的值。
• Type是定义新/自定义Output Formats时必须使用的标识符（见下文）。
• 完整的媒体类型集将在Hugo的内置开发服务器中注册，以确保它们被浏览器识别。

​ 要添加或修改媒体类型，请在站点配置中的mediaTypes部分中定义它，可以为所有站点或特定语言定义。

config.

=== “yaml”

``` yaml
mediaTypes:
  text/enriched:
    suffixes:
    - enr
  text/html:
    suffixes:
    - asp
```

=== “toml”

``` toml
[mediaTypes]
  [mediaTypes.'text/enriched']
    suffixes = ['enr']
  [mediaTypes.'text/html']
    suffixes = ['asp']
```

=== “json”

``` json
{
   "mediaTypes": {
      "text/enriched": {
         "suffixes": [
            "enr"
         ]
      },
      "text/html": {
         "suffixes": [
            "asp"
         ]
      }
   }
}
```

​ 上面的示例添加了一个新的媒体类型text/enriched，并更改了内置的text/html媒体类型的后缀。

注意：这些媒体类型是针对您的输出格式进行配置的。如果要重新定义Hugo的默认输出格式（例如HTML），还需要重新定义媒体类型。因此，如果要将HTML输出格式的后缀从html（默认）更改为htm：

config.

=== “yaml”

``` yaml
mediaTypes:
  text/html:
    suffixes:
    - htm
outputFormats:
  HTML:
    mediaType: text/html
```

=== “toml”

``` toml
[mediaTypes]
  [mediaTypes.'text/html']
    suffixes = ['htm']
[outputFormats]
  [outputFormats.HTML]
    mediaType = 'text/html'
```

=== “json”

``` json
{
   "mediaTypes": {
      "text/html": {
         "suffixes": [
            "htm"
         ]
      }
   },
   "outputFormats": {
      "HTML": {
         "mediaType": "text/html"
      }
   }
}
```

注意，要让上述内容生效，您还需要在站点配置中添加 outputs 定义。

输出格式定义

​ 给定一个媒体类型和一些其他配置，您可以获得一个输出格式。

​ 这是Hugo的所有内置输出格式：

• 一个页面可以按您想要的多种输出格式输出，只要它们在文件系统上解析为唯一路径即可定义无限数量的输出格式。在上面的表格中，最好的例子是AMP vs HTML。AMP的Path值为amp，因此不会覆盖HTML版本。例如，我们现在可以同时拥有 /index.html 和 /amp/index.html。
• MediaType 必须匹配已定义媒体类型的Type。
• 您可以定义新的输出格式或重新定义内置的输出格式；例如，如果您想将AMP页面放在不同的路径中。

​ 要添加或修改输出格式，请在站点配置文件中的 outputFormats 部分中定义它，无论是为所有站点还是为给定的语言。

config.

=== “yaml”

``` yaml
outputFormats:
  MyEnrichedFormat:
    baseName: myindex
    isPlainText: true
    mediaType: text/enriched
    protocol: bep://
```

=== “toml”

``` toml
[outputFormats]
  [outputFormats.MyEnrichedFormat]
    baseName = 'myindex'
    isPlainText = true
    mediaType = 'text/enriched'
    protocol = 'bep://'
```

=== “json”

``` json
{
   "outputFormats": {
      "MyEnrichedFormat": {
         "baseName": "myindex",
         "isPlainText": true,
         "mediaType": "text/enriched",
         "protocol": "bep://"
      }
   }
}
```

​ 上述示例是虚构的，但如果用于具有 baseURL https://example.org 的站点的主页，它将产生一个具有 URL bep://example.org/myindex.enr 的纯文本主页。

配置输出格式

​ 以下是输出格式的完整配置选项列表及其默认值：

• name

  输出格式标识符。用于定义您页面的输出格式。

• mediaType

  这必须与已定义的媒体类型的Type匹配。

• path

  保存输出文件的子路径。

• baseName

  用于列表文件名（主页等）的基本文件名。默认值：index。

• rel

  可用于在link标记中创建 rel 值。默认值：alternate。

• protocol

  将替换 baseURL 中此输出格式的"http://“或"https://"。

• isPlainText

  使用 Go 的纯文本模板解析器进行模板解析。默认值： false。

• isHTML

  仅在与 HTML 类型格式相关的情况下使用，例如页面别名。默认值： false。

• noUgly

  用于关闭丑陋的 URL（如果在站点中设置了 uglyURLs为 true）。默认值： false。

• notAlternative

  enable if it doesn’t make sense to include this format in an AlternativeOutputFormats format listing on Page (e.g., with CSS). Note that we use the term alternative and not alternate here, as it does not necessarily replace the other format. Default: false.

  如果在Page的 AlternativeOutputFormats 格式列表中包含此格式不合理（例如使用 CSS），则启用此选项。请注意，此处我们使用 alternative 而不是 alternate 一词，因为它并不一定替代其他格式。默认值： false。

• permalinkable

  使 .Permalink 和 .RelPermalink 返回渲染输出格式而不是主格式（见下文）。默认情况下，对于 HTML 和 AMP 启用此选项。默认值： false。

• weight

  将其设置为非零值将用作第一个排序标准。

页面的输出格式

​ 在 Hugo 中，Page可以在文件系统上呈现为多种输出格式。

默认输出格式

​ 每个Page都有一个 Kind 属性，其默认输出格式是基于此属性设置的。

自定义输出格式

​ 这可以通过在Page前置元数据或站点配置（对所有站点或每种语言）中定义一个outputs列表来更改。

​ 站点配置文件中的示例：

config.

=== “yaml”

``` yaml
outputs:
  home:
  - HTML
  - AMP
  - RSS
  page:
  - HTML
```

=== “toml”

``` toml
[outputs]
  home = ['HTML', 'AMP', 'RSS']
  page = ['HTML']
```

=== “json”

``` json
{
   "outputs": {
      "home": [
         "HTML",
         "AMP",
         "RSS"
      ],
      "page": [
         "HTML"
      ]
   }
}
```

请注意，在上面的示例中，section、taxonomy和term的输出格式将保持其默认值 ["HTML", "RSS"]。

• outputs 定义是每种Page的 Kind（page、home、section、taxonomy 或 term）的。

• These can be overridden per Page in the front matter of content files.

• 所使用的名称（例如 HTML、AMP）必须与已定义的输出格式的Name匹配。

  这些名称不区分大小写。

• 这些可以在内容文件的前置元数据中针对每个Page进行覆盖。

​ 以下是一个在内容文件中定义呈现Page输出格式的前置元数据的示例：

content/example.md

=== “yaml”

``` yaml
---
outputs:
- html
- amp
- json
title: Example
---
```

=== “toml”

``` toml
+++
outputs = ['html', 'amp', 'json']
title = 'Example'
+++
```

=== “json”

``` json
{
   "outputs": [
      "html",
      "amp",
      "json"
   ],
   "title": "Example"
}
```

输出格式列表

​ 每个Page都有 .OutputFormats（所有格式，包括当前格式）和 .AlternativeOutputFormats 变量，后者可用于在站点的 <head> 中创建link rel 列表。

1
2
3

{{ range .AlternativeOutputFormats -}}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end -}}

输出格式链接

​ Page 上的 .Permalink 和 .RelPermalink 将返回为该页面定义的第一个输出格式（通常为 HTML，如果没有其他定义的话）。这与调用它们的模板文件无关。

来自 single.json.json：

1
2
3
4

{{ .RelPermalink }} > /that-page/
{{ with  .OutputFormats.Get "json" -}}
{{ .RelPermalink }} > /that-page/index.json
{{- end }}

​ 为了使它们返回当前模板文件的输出格式，给定的输出格式应设置其 permalinkable 属性为 true。

与上面相同的模板文件，带有json 输出格式的 permalinkable 设置为 true：

1
2
3
4

{{ .RelPermalink }} > /that-page/index.json
{{ with  .OutputFormats.Get "html" -}}
{{ .RelPermalink }} > /that-page/
{{- end }}

​ 从内容文件中，您可以使用 ref 或 relref 简码：

1
2

[Neat](\{\{\< ref "blog/neat.md" "amp" \>\}\})
[Who](\{\{\< relref "about.md#who" "amp" \>\}\})

您的输出格式模板

​ 一个新的输出格式需要一个相应的模板才能渲染任何有用的内容。

​ 对于 Hugo 0.20 及更高版本的关键区别在于，Hugo 查看输出格式的 Name 和 MediaType 的 Suffixes，以选择用于渲染给定 Page 的模板。

​ 以下表格显示了不同输出格式的示例、所使用的后缀以及 Hugo 的模板查找顺序。表格中的所有示例都可以：

• 使用基础模板。
• 包含局部模板。

​ Hugo 现在还可以检测 partials 的媒体类型和输出格式（如果可能的话），并使用这些信息来决定是否将 partial 解析为纯文本模板。

​ Hugo将查找给定的名称，因此您可以根据需要随意命名它。但是，如果要将其视为纯文本，请使用文件后缀，如果需要，还要使用输出格式的名称。 模式如下：

1

[partial name].[OutputFormat].[suffix]

​ 以下 partial 是一个纯文本模板（输出格式为 CSV，由于这是唯一带有后缀 csv 的输出格式，因此我们不需要包含输出格式的Name）：

1

{{ partial "mytextpartial.csv" . }}

另请参阅

• Hugo中的内容列表
• RSS模板

4 - 基础模板和块

Base Templates and Blocks - 基础模板和块

https://gohugo.io/templates/base/

​ 基本模板和块结构允许您定义主模板的外壳（即页面的Chrome）。

​ block关键字允许您定义页面一个或多个主模板的外壳，然后根据需要填充或覆盖部分（portions ）。

基础模板查找顺序

​ 基础模板查找顺序紧跟它所应用的模板的查找顺序（例如，_default/list.html）。

​ 有关详细信息和示例，请参见模板查找顺序。

定义基础模板

​ 以下定义了一个简单的基础模板 _default/baseof.html。作为默认模板，它是从所有页面渲染的外壳，除非您在查找顺序的开头指定另一个*baseof.html。

layouts/_default/baseof.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ block "title" . }}
      <!-- Blocks may include default content. -->
      {{ .Site.Title }}
    {{ end }}</title>
  </head>
  <body>
    <!-- Code that all your templates share, like a header -->
    {{ block "main" . }}
      <!-- The part of the page that begins to differ between templates -->
    {{ end }}
    {{ block "footer" . }}
    <!-- More shared code, perhaps a footer but that can be overridden if need be in  -->
    {{ end }}
  </body>
</html>

覆盖基础模板

​ 从上面的基本模板，您可以定义默认的列表模板。默认的列表模板将继承上面定义的所有代码，然后可以根据需要实现自己的"main"块：

layouts/_default/list.html

1
2
3
4
5
6
7
8
9

{{ define "main" }}
  <h1>Posts</h1>
  {{ range .Pages }}
    <article>
      <h2>{{ .Title }}</h2>
      {{ .Content }}
    </article>
  {{ end }}
{{ end }}

​ 这将用实际有用的内容替换我们（基本上为空的）"main"块的内容，对于列表中的内容，我们没有定义"title"块，因此在列表中保留了来自基础模板的内容。

​ 放置在块定义之外的代码会破坏您的布局，这甚至包括HTML注释。例如：

1
2
3
4

<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
{{ end }}

请参见Hugo讨论论坛中的此主题。

​ 以下显示了如何使用特定于默认单个页面模板的代码覆盖基础模板的"main"和"title"块区域：

layouts/_default/single.html

1
2
3
4
5
6
7
8

{{ define "title" }}
  <!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
  {{ .Title }} &ndash; {{ .Site.Title }}
{{ end }}
{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

另请参阅

• path.Base
• path.BaseName

5 - Markdown渲染钩子

Markdown Render Hooks - Markdown渲染钩子

https://gohugo.io/templates/render-hooks/

​ 渲染钩子允许自定义模板覆盖markdown渲染功能。

​ 请注意，这只支持Goldmark渲染器。

​ 您可以通过在layouts/_default/_markup中创建名称为render-{kind}的模板来覆盖默认的Markdown渲染为HTML的某些部分。

​ 您还可以在layouts/[type/section]/_markup中创建特定于type/section的钩子，例如：layouts/blog/_markup。

​ 目前支持的钩子种类有：

• image
• link
• heading
• codeblock New in v0.93.0

​ 如果需要，您可以定义特定于输出格式和语言的模板。您的layouts文件夹可能如下所示：

1
2
3
4
5
6
7
8
9

layouts/
└── _default/
    └── _markup/
        ├── render-codeblock-bash.html
        ├── render-codeblock.html
        ├── render-heading.html
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

​ 以下是上述用法的一些示例：

• 使用.GetPage解析链接引用。这将使链接可移植，因为您可以将./my-post.md（和在GitHub上可以使用的类似构造）转换为/blog/2019/01/01/my-post/等。
• 为外部链接添加target=_blank。
• 解析和处理图像。
• 添加标题链接。

渲染钩子应用于标题、链接和图像

传递给render-link和render-image的上下文

​ render-link和render-image模板将接收到以下上下文：

• Page

  正在被渲染的Page。

• Destination

  The URL.

• Title

  title属性。

• Text

  渲染后的（HTML）链接文本。

• PlainText

  上述文本的纯文本版本。

传递给render-heading的上下文

​ render-heading模板将接收以下上下文：

• Page

  正在被渲染的页面。

• Level

  标题级别（1-6）

• Anchor

  在该页面中唯一的自动生成的HTML id。

• Text

  被渲染后的（HTML）文本。

• PlainText

  上述内容的纯文本版本。

• Attributes (map)

  一个属性映射（例如id、class）。需要注意的是，对于链接，这个映射目前始终为空。

The render-image templates will also receive:

​ render-image模板还将接收：

• IsBlock New in v0.108.0

  如果这是一个独立的图像并且配置选项markup.goldmark.parser.wrapStandAloneImageWithinParagraph被禁用，则返回true。

• Ordinal New in v0.108.0

  当前文档中所有图像的基于零的序数。

带标题的Markdown链接示例

1

[Text](https://www.gohugo.io "Title")

​ 以下是render-link.html模板的代码示例：

layouts/_default/_markup/render-link.html

1

<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

图像Markdown示例

1

![Text](https://gohugo.io/images/hugo-logo-wide.svg "Title")

​ 以下是render-image.html模板的代码示例：

layouts/_default/_markup/render-image.html

1
2
3

<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
</p>

标题链接示例

​ 给定此模板文件

layouts/_default/_markup/render-heading.html

1

<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>

​ 以及这个 markdown

1

### Section A

​ 渲染出的 HTML 代码将是

1

<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>

代码块的渲染钩子

New in v0.93.0

​ 您可以为所有代码块或特定类型/语言（例如下面的bash）添加钩子模板：

​ 这些代码块的默认行为是进行代码高亮，但是由于可以向这些代码块传递属性，因此它们可以用于几乎任何事情。一个示例是内置的GoAT Diagrams或这个Mermaid Diagram Code Block Hook示例。

​ 代码块模板中您可以获取到的上下文（"."）包括：

• Type (string)

  代码块的类型。这将是编程语言，例如bash，用于进行代码高亮。

• Attributes (map)

  从Markdown传递的属性（例如{ attrName1=attrValue1 attrName2="attr Value 2" }）。

• Options (map)

  Chroma 高亮处理选项。仅在 Type 是已知的 Chroma Lexer 时才填充。

• Inner (string)

  代码围栏之间的文本。

• Ordinal (integer)

  当前文档中所有代码块的从零开始的序数。

• Page

  所属的Page。

• Position

  在错误日志中有用，因为它会打印出文件名和位置（行号、列号），例如 {{ errorf "error in code block: %s" .Position }}。

另请参阅

• .RenderString
• [内容格式 (https://gohugo.io/content-management/formats/)
• 简码
• anchorize
• markdownify

6 - 在Hugo中的内容列表

Lists of Content in Hugo - 在Hugo中的内容列表

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

​ 列表在 Hugo 中在渲染站点主页、章节页面、分类列表或分类术语列表时具有特定的含义和用法。

什么是列表页面模板？

​ 列表页面模板是用于在单个 HTML 页面中渲染多个内容的模板。唯一的例外是主页，它仍然是一个列表，但有自己的专用模板。

​ Hugo 在其最真实的意义上使用列表这个术语；即按字母或数字顺序的一系列材料。Hugo 在任何传统上列出内容的输出 HTML 页面上都使用列表模板：

• 分类术语页面
• 分类列表页面
• 章节列表页面
• RSS

​ 有关模板查找顺序，请参见模板查找。

​ 列表页面的概念源于Web的分层心理模型，最好通过可视化进行演示：

列表默认值

默认模板

​ 由于章节列表和分类列表（注意，不是分类术语列表）在模板方面都是列表，因此它们在查找顺序中都有相同的终止默认值 _default/list.html 或 themes/<THEME>/layouts/_default/list.html。此外，章节列表和分类列表在 _default 中都有自己的默认列表模板。

​ 有关完整参考，请参阅模板查找顺序。

将内容和前置元数据添加到列表页

​ 自从 v0.18 以来，Hugo 中的所有内容都是Page。这意味着列表页面和主页可以有关联的内容文件（即_index.md），其中包含页面元数据（即前置元数据）和内容。

​ 这种新模型允许您通过 .Params 包含特定于列表的前置元数据，并且意味着列表模板（例如 layouts/_default/list.html）可以访问所有页面变量。

​ 重要的是要注意，所有 _index.md 内容文件都将根据列表模板而不是单个页面模板进行渲染。

示例项目目录

​ 以下是一个典型的Hugo项目的content目录的示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

.
...
├── content
|   ├── posts
|   |   ├── _index.md
|   |   ├── post-01.md
|   |   └── post-02.md
|   └── quote
|   |   ├── quote-01.md
|   |   └── quote-02.md
...

​ 使用上述示例，假设您在content/posts/_index.md中有以下内容：

content/posts/_index.md

1
2
3
4
5
6
7
8
9

---
title: My Go Journey
date: 2017-03-23
publishdate: 2017-03-24
---

I decided to start learning Go in March 2017.

Follow my journey through this new blog.

​ 现在，您可以在列表模板中访问此_index.md的内容：

layouts/_default/list.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{{ define "main" }}
<main>
  <article>
    <header>
      <h1>{{ .Title} }</h1>
    </header>
    <!-- "{{ .Content} }" pulls from the markdown content of the corresponding _index.md -->
    {{ .Content }}
  </article>
  <ul>
    <!-- Ranges through content/posts/*.md -->
    {{ range .Pages }}
      <li>
        <a href="{{ .Permalink }}">{{ .Date.Format "2006-01-02" }} | {{ .Title }}</a>
      </li>
    {{ end }}
  </ul>
</main>
{{ end }}

​ 上面将输出以下 HTML：

example.com/posts/index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

<!--top of your baseof code-->
<main>
    <article>
        <header>
            <h1>My Go Journey</h1>
        </header>
        <p>I decided to start learning Go in March 2017.</p>
        <p>Follow my journey through this new blog.</p>
    </article>
    <ul>
        <li><a href="/posts/post-01/">Post 1</a></li>
        <li><a href="/posts/post-02/">Post 2</a></li>
    </ul>
</main>
<!--bottom of your baseof-->

没有 _index.md 的列表页面

​ 您不必为每个列表页面（即章节、分类、分类术语等）或主页创建 _index.md 文件。如果 Hugo 在渲染列表模板时在相应的内容章节中找不到 _index.md，则将创建该页面，但没有 {{ .Content }}，只有 .Title 等的默认值。

​ 将相同的 layouts/_default/list.html 模板应用于上面的 quotes 章节将渲染以下输出。请注意，quotes 没有可供提取的 _index.md 文件：

example.com/quote/index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<!--baseof-->
<main>
    <article>
        <header>
        <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
            <h1>Quotes</h1>
        </header>
    </article>
    <ul>
        <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
        <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
    </ul>
</main>
<!--baseof-->

默认情况下，Hugo会将列表标题进行复数化处理，因此在使用 .Title 页面变量时，quote部分会变为"Quotes"。您可以通过在站点配置中使用pluralizeListTitles指令来更改此设置。

示例列表模板

章节模板

​ 这个列表模板是从spf13.com的模板进行了略微修改。它使用局部模板来渲染页面的外壳，而不是使用基础模板。下面的示例还使用了内容视图模板 li.html 或 summary.html。

layouts/section/posts.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<main>
  <div>
   <h1>{{ .Title }}</h1>
        <ul>
        <!-- Renders the li.html content view for each content/posts/*.md -->
            {{ range .Pages }}
                {{ .Render "li" }}
            {{ end }}
        </ul>
  </div>
</main>
{{ partial "footer.html" . }}

分类模板

layouts/_default/taxonomy.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{ define "main" }}
<main>
  <div>
   <h1>{{ .Title }}</h1>
   <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
    {{ range .Pages }}
        {{ .Render "summary" }}
    {{ end }}
  </div>
</main>
{{ end }}

内容排序

​ Hugo 根据您在前置元数据中提供的内容来渲染列表。除了合理的默认值外，Hugo 还提供了多种方法，以便在列表模板内快速进行内容排序：

Default: Weight > Date > LinkTitle > FilePath

layouts/partials/default-order.html

1
2
3
4
5
6
7
8

<ul>
    {{ range .Pages }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按权重

​ 较低的权重具有较高的优先级。因此，权重较低的内容将排在前面。

layouts/partials/by-weight.html

1
2
3
4
5
6
7
8

<ul>
    {{ range .Pages.ByWeight }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按日期

layouts/partials/by-date.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- orders content according to the "date" field in front matter -->
    {{ range .Pages.ByDate }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按发布日期

layouts/partials/by-publish-date.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- orders content according to the "publishdate" field in front matter -->
    {{ range .Pages.ByPublishDate }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按到期日期

layouts/partials/by-expiry-date.html

1
2
3
4
5
6
7
8

<ul>
    {{ range .Pages.ByExpiryDate }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按最后修改日期

layouts/partials/by-last-mod.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- orders content according to the "lastmod" field in front matter -->
    {{ range .Pages.ByLastmod }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按长度

layouts/partials/by-length.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
    {{ range .Pages.ByLength }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按标题

layouts/partials/by-title.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- ranges through content in ascending order according to the "title" field set in front matter -->
    {{ range .Pages.ByTitle }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按链接标题

layouts/partials/by-link-title.html

1
2
3
4
5
6
7
8
9

<ul>
    <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
    {{ range .Pages.ByLinkTitle }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

按参数

​ 根据指定的前置元数据参数进行排序。如果内容没有指定的前置元数据字段，则使用站点的 .Site.Params 默认值。如果在某些条目中根本找不到该参数，这些条目将一起出现在排序的末尾。

layouts/partials/by-rating.html

1
2
3
4

<!-- Ranges through content according to the "rating" field set in front matter -->
{{ range (.Pages.ByParam "rating") }}
  <!-- ... -->
{{ end }}

​ 如果目标的前置元数据字段嵌套在另一个字段下，则您可以使用点表示法来访问该字段。

layouts/partials/by-nested-param.html

1
2
3

{{ range (.Pages.ByParam "author.last_name") }}
  <!-- ... -->
{{ end }}

倒序排序

​ 可以将倒序排序应用于上述任何一种方法。以下示例以 ByDate 为例：

layouts/partials/by-date-reverse.html

1
2
3
4
5
6
7
8

<ul>
    {{ range .Pages.ByDate.Reverse }}
        <li>
            <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
            <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
        </li>
    {{ end }}
</ul>

分组内容

​ Hugo 提供一些函数，可按章节、类型、日期等对页面进行分组。

按页面字段

layouts/partials/by-page-field.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
{{ range .Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

​ 在上面的例子中，您可能希望 {{ .Title }} 指向您已添加到 _index.md 文件中的title字段。您可以使用 .GetPage 函数来访问此值：

layouts/partials/by-page-field.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<!-- Groups content according to content section.-->
{{ range .Pages.GroupBy "Section" }}
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
{{ with $.Site.GetPage "section" .Key }}
<h3>{{ .Title }}</h3>
{{ else }}
<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
<h3>{{ .Key | title }}</h3>
{{ end }}
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

按日期

layouts/partials/by-page-date.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content by month according to the "date" field in front matter -->
{{ range .Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

在新版本 v0.97.0 中，GroupByDate 函数接受与 time.Format 中相同的时间格式，并且结果中的 .Key 会根据当前语言进行本地化。

按发布日期

layouts/partials/by-page-publish-date.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content by month according to the "publishDate" field in front matter -->
{{ range .Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

在新版本 v0.97.0 中，GroupByDate 函数接受与 time.Format 中相同的时间格式，并且结果中的 .Key 会根据当前语言进行本地化。

按照上次修改时间

layouts/partials/by-page-lastmod.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content by month according to the "lastMod" field in front matter -->
{{ range .Pages.GroupByLastmod "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

在新版本 v0.97.0 中，GroupByDate 函数接受与 time.Format 中相同的时间格式，并且结果中的 .Key 会根据当前语言进行本地化。

按过期日期

layouts/partials/by-page-expiry-date.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content by month according to the "expiryDate" field in front matter -->
{{ range .Pages.GroupByExpiryDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

在新版本 v0.97.0 中，GroupByDate 函数接受与 time.Format 中相同的时间格式，并且结果中的 .Key 会根据当前语言进行本地化。

按照页面参数

layouts/partials/by-page-param.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content according to the "param_key" field in front matter -->
{{ range .Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

按照页面参数和日期格式

​ 在按date分组的模板中，使用了 Go 的布局字符串来进一步分组。有关如何使用 Go 的布局字符串格式化 Hugo 中的日期的更多示例，请参见 Format 函数。

layouts/partials/by-page-param-as-date.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Groups content by month according to the "param_key" field in front matter -->
{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

反向键顺序

​ 分组的排序是按字母数字顺序的键进行排序（A-Z、1-100），并按照日期的逆序排列（即，最新的日期排在最前面）。

​ 虽然这些是逻辑上的默认值，但并不总是期望的排序。有两种不同的语法可以更改 Hugo 的默认分组排序，它们都以相同的方式工作。

1. 添加 Reverse 方法

1
2

{{ range (.Pages.GroupBy "Section").Reverse }}
{{ range (.Pages.GroupByDate "2006-01").Reverse }}

2. 提供另一种方向

1
2

{{ range .Pages.GroupByDate "2006-01" "asc" }}
{{ range .Pages.GroupBy "Section" "desc" }}

组内排序

​ 由于Grouping返回一个{{ .Key }}和一个页面片段，因此上述所有排序方法都可用。

​ 以下是示例的排序方式：

1. 根据前置元数据中的date字段按月份分组内容。
2. 按升序列出分组（即最旧的分组先列出）。
3. 每个分组内的页面根据title按字母顺序排序。

layouts/partials/by-group-by-page.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{ range .Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
    {{ range .Pages.ByTitle }}
    <li>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
    <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
    </li>
    {{ end }}
</ul>
{{ end }}

筛选和限制列表

​ 有时，您只想列出可用内容的子集。一个常见的方法是仅在博客主页上显示主要章节的文章。

​ 有关详细信息，请参见where函数和first函数的文档。

另请参阅

• .GetPage
• 内容章节
• 内容类型
• 菜单模板
• 分页

7 - 主页模板

Homepage Template - 主页模板

https://gohugo.io/templates/homepage/

​ 站点的主页通常与其他页面格式不同。因此，Hugo 使您能够轻松地将新站点的主页定义为独特的模板。

​ 主页是一个Page，因此可使用所有页面变量和站点变量。

​ 主页模板是构建站点所必需的唯一模板，因此在启动新站点和模板时非常有用。如果您正在开发单页面站点，则它也是唯一必需的模板。

主页模板查找顺序

​ 请参见模板查找。

向主页添加内容和前置元数据

​ 主页与 Hugo 中的其他列表页面类似，可以从 _index.md 文件接受内容和 前置元数据。该文件应该位于您的 content 文件夹的根目录下（即 content/_index.md）。然后，您可以像处理其他任何内容文件一样向主页添加正文和元数据（metadata ）。

​ 有关如何使用 _index.md 向列表页面添加内容和前置元数据的更多信息，请参见下面的主页模板或内容组织。

示例主页模板

​ 以下是一个主页模板示例，它使用 partial、基础模板和位于 content/_index.md 中的内容文件来填充 {{ .Title }} 和 {{ .Content }} 页面变量。

layouts/index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{{ define "main" }}
  <main aria-role="main">
    <header class="homepage-header">
      <h1>{{ .Title }}</h1>
      {{ with .Params.subtitle }}
      <span class="subtitle">{{ . }}</span>
      {{ end }}
    </header>
    <div class="homepage-content">
      <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
      {{ .Content }}
    </div>
    <div>
      {{ range first 10 .Site.RegularPages }}
          {{ .Render "summary" }}
      {{ end }}
    </div>
  </main>
{{ end }}

8 - 分类法（Taxonomy）模板

Taxonomy Templates - 分类法（Taxonomy）模板

https://gohugo.io/templates/taxonomy-templates/

​ Taxonomy（分类法）模板包括分类法列表页面、分类法条目页面以及在单页模板中使用分类法。

​ Hugo 支持用户定义的内容分组，称为分类法。分类法是展示内容之间逻辑关系的分类法方法。如果您对 Hugo 如何利用这个强大功能不熟悉，请参见内容管理下的分类法。

​ Hugo 提供了多种在项目模板中使用分类法的方式：

• 按照与分类法条目相关联的内容的方式在分类法列表模板中显示。
• 以特定的顺序显示与分类法条目相关联的内容，具体方法是在分类法列表模板中设置排序方式。
• 按照分类法的方式在分类法条目模板中显示。
• 在单页模板中列出单个内容的分类法条目。

分类法列表模板

​ 分类法列表页面模板是列表，因此具有可用于列表页面的所有变量和方法。

分类法列表模板查找顺序

​ 请参见模板查找。

分类法条目模板

分类法条目模板查找顺序

​ 请参见模板查找。

分类法方法

A Taxonomy is a map[string]WeightedPages.

​ 分类法是一个 map[string]WeightedPages。

• .Get(term)

  返回条目的 WeightedPages。

• .Count(term)

  分配给该条目的内容数量。

• .Alphabetical

  Returns an OrderedTaxonomy (slice) ordered by Term.

  返回一个按条目排序的 OrderedTaxonomy（切片）。

• .ByCount

  返回一个按条目数量排序的 OrderedTaxonomy（切片）。

• .Reverse

  返回一个按相反顺序排序的 OrderedTaxonomy（切片）。必须与 一个OrderedTaxonomy 一起使用。

OrderedTaxonomy

​ 由于 Map 是无序的，因此 OrderedTaxonomy 是一个具有定义顺序的特殊结构。

1
2
3
4

[]struct {
    Name          string
    WeightedPages WeightedPages
}

​ 该切片的每个元素都有：

• .Term

  使用的条目。

• .WeightedPages

  一个加权页面的切片。

• .Count

  分配给该条目的内容数量。

• .Pages

  分配给该条目的所有页面。所有列表方法都可用于此。

WeightedPages

​ WeightedPages是WeightedPage的一个切片。

1

type WeightedPages []WeightedPage

• .Count(term)

  被分配到此条目的内容数量。

• .Pages

  返回一个页面的切片，可以使用任何 列表方法 进行排序。

在分类法条目模板中显示自定义元数据

​ 如果您需要为每个分类法条目显示自定义元数据，您需要在/content/<TAXONOMY>/<TERM>/_index.md路径下为该条目创建一个页面，并在其前置元数据中添加元数据，如分类法文档中所述。以其中显示的演员分类法为例，在您的分类法条目模板中，您可以通过迭代变量.Pages来访问您的自定义字段：

1
2
3
4
5
6
7
8

<ul>
    {{ range .Pages }}
        <li>
            <a href="{{ .Permalink }}">{{ .Title }}</a>
            {{ .Params.wikipedia }}
        </li>
    {{ end }}
</ul>

排序分类法

​ 分类法可以按字母键或分配给该键的内容数量排序。

按字母顺序示例

1
2
3
4
5

<ul>
    {{ range .Data.Terms.Alphabetical }}
            <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
    {{ end }}
</ul>

在分类法中排序内容

​ Hugo在分类法中使用date和weight来排序内容。

​ 在 Hugo 中，每篇内容可以选择性地被分配一个日期。它也可以为每个所属分类法分配一个权重。

​ 当在分类法中迭代内容时，默认排序方式与用于章节和列表页面相同：首先按权重，然后按日期排序。这意味着，如果两篇内容的权重相同，则最近日期的内容将首先显示。

​ 任何一篇内容的默认权重为0。零意味着"does not have a weight"，而不是"has a weight of numerical value zero"。

​ 因此，权重为零的条目被特殊处理：如果两个页面的权重不相等，并且其中一个是零，则具有零权重的页面将始终出现在另一个页面之后，而不用考虑另一个页面的权重。因此，应谨慎使用零权重：例如，如果正权重和负权重都用于在两个方向上扩展序列，则具有零权重的页面将不会出现在列表的中间，而是在末尾。

分配权重

​ 每个内容可以分别为它所属的每个分类法（taxonomies）赋予一个权重（weight）。

content/example.md

=== “yaml”

``` yaml
---
categories:
- d
categories_weight: 44
tags:
- a
- b
- c
tags_weight: 22
title: Example
---
```

=== “toml”

``` toml
+++
categories = ['d']
categories_weight = 44
tags = ['a', 'b', 'c']
tags_weight = 22
title = 'Example'
+++
```

=== “json”

``` json
{
   "categories": [
      "d"
   ],
   "categories_weight": 44,
   "tags": [
      "a",
      "b",
      "c"
   ],
   "tags_weight": 22,
   "title": "Example"
}
```

​ 惯例是使用taxonomyname_weight。

​ 在上面的例子中，这篇内容在渲染分配给"tag" 分类法中的"a"、“b” 和 “c” 值的页面时具有22的权重。

​ 在渲染’d’类别时，它还被赋予了44的权重。

​ 这样做可以使同一篇内容在不同的分类法中出现在不同的位置。

​ 目前，分类法仅支持默认的内容排序方式，即权重->日期。

​ 使用分类法将需要提供两种不同的模板。

​ 这两中模板在模板章节中都有详细介绍。

​ 列表模板是用于在单个HTML页面中渲染多篇内容的任一模板。此模板将用于生成所有自动创建的分类法页面。

​ 分类法模板是用于生成给定模板的条目列表的模板。

​ 除了使用 Hugo 自动生成的 列表模板 来创建分类法页面外，还有四种常见的方式可以展示您的分类法数据：

1. 对于给定篇的内容，您可以列出附加的条目
2. 对于给定篇的内容，您可以列出具有相同条目的其他内容
3. 您可以列出某一分类法的所有条目
4. 您可以列出所有分类法（及其条目）

显示单篇内容的分类法

​ 在内容模板中，您可能希望显示分配给该内容的分类法。

​ 由于我们利用前置元数据系统为内容定义分类法，因此分配给每篇内容的分类法位于通常的位置（即 .Params.<TAXONOMYPLURAL>）。

示例：在单页模板中列出标签

1
2
3
4
5

<ul>
    {{ range (.GetTerms "tags") }}
        <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
</ul>

​ 如果您想要内联列出分类法，您将需要注意标题中的可选复数结尾（如果有多个分类法），以及逗号。假设我们有一个名为 “directors” 的分类法，如 TOML 格式的前置元数据所示：directors: [ "Joel Coen", "Ethan Coen" ]。

​ 要列出这样的分类法，请使用以下方法：

示例：在单页模板中使用逗号分隔标签

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{{ $taxo := "directors" }} <!-- Use the plural form here -->
{{ with .Param $taxo }}
    <strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong>
    {{ range $index, $director := . }}
        {{- if gt $index 0 }}, {{ end -}}
        {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}}
            <a href="{{ .Permalink }}">{{ $director }}</a>
        {{- end -}}
    {{- end -}}
{{ end }}

​ 或者，如果只需要使用分隔符列出分类法，则可以使用delimit 模板函数作为快捷方式。详见GitHub上的#2143讨论。

列出具有相同分类法条目的内容

​ 如果您正在使用分类法来管理一系列文章，您可以列出与同一分类法相关联的各个页面。这也是一种快速粗略的方法来展示相关内容：

示例：显示同一系列的内容

1
2
3
4
5

<ul>
    {{ range .Site.Taxonomies.series.golang }}
        <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
    {{ end }}
</ul>

列出给定分类法中的所有内容

​ 这在侧边栏中作为"特色内容"将非常有用。您甚至可以通过为内容分配不同的条目来创建不同的"特色内容" 章节。

示例：对"Featured"内容进行分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<section id="menu">
    <ul>
        {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
        <li>{{ $key }}</li>
        <ul>
            {{ range $taxonomy.Pages }}
            <li hugo-nav="{{ .RelPermalink }}"><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
            {{ end }}
        </ul>
        {{ end }}
    </ul>
</section>

渲染站点的分类法

​ 如果您希望显示站点分类法的所有键列表，可以从每个页面都可以访问的.Site变量中检索它们。

​ 这可以采用标签云、菜单或简单列表的形式。

​ 以下示例显示站点标签分类法中的所有条目：

示例：列出所有站点标签

1
2
3
4
5

<ul>
    {{ range .Site.Taxonomies.tags }}
            <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
    {{ end }}
</ul>

示例：列出所有分类法、条目和分配的内容

​ 这个示例将列出所有分类法及其条目，以及分配给每个条目的所有内容。

layouts/partials/all-taxonomies.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<section>
    <ul id="all-taxonomies">
        {{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}
            {{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }}
                <li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a>
                    <ul>
                        {{ range $key, $value := $taxonomy }}
                            <li>{{ $key }}</li>
                            <ul>
                                {{ range $value.Pages }}
                                    <li hugo-nav="{{ .RelPermalink }}">
                                        <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
                                    </li>
                                {{ end }}
                            </ul>
                        {{ end }}
                    </ul>
                </li>
            {{ end }}
        {{ end }}
    </ul>
</section>

.Site.GetPage 用于分类法

​ 由于分类法是列表，可以使用.GetPage函数使用简洁的语法获取与特定分类法条目相关联的所有页面。下面对站点上所有标签进行全面的遍历，并链接到每个条目的单独分类页面，而不必使用上面的"列出所有站点标签"示例中更脆弱的URL构建方法：

links-to-all-tags.html

1
2
3
4
5
6
7
8

{{ $taxo := "tags" }}
<ul class="{{ $taxo }}">
    {{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
        {{ range .Pages }}
            <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
        {{ end }}
    {{ end }}
</ul>

另请参阅

• 分类法
• 原型
• 前置元数据
• Hugo 中的内容列表
• .Param

9 - 章节页面模板

Section Page Templates - 章节页面模板

https://gohugo.io/templates/section-templates/

​ 用于章节页面的模板是列表，因此具有所有可用于列举页面的变量和方法。

向章节模板添加内容和前置元数据

​ 为了有效利用章节页面模板，您应首先了解Hugo的内容组织方式，特别是添加内容和前置元数据到章节和其他列表页面的_index.md文件的目的。

章节模板查找顺序

​ 请参见模板查找。

页面种类

​ Hugo 中的每个Page都有一个 .Kind 属性。

.Site.GetPage with Sections

​ .Kind可以轻松地与模板中的where函数结合使用，创建特定类型的内容列表。这种方法非常适合创建列表，但有时您可能想通过章节的路径获取单个章节的索引页面。

​ .GetPage函数查找给定Kind和path的索引页。

​ 您可以使用两个参数调用.Site.GetPage：kind（上述有效Kind之一）和kind value。

例如：

• {{ .Site.GetPage "section" "posts" }}
• {{ .Site.GetPage "page" "search" }}

示例：创建默认章节模板

layouts/_default/section.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{{ define "main" }}
  <main>
      {{ .Content }}
          <ul class="contents">
          {{ range .Paginator.Pages }}
              <li>{{ .Title }}
                  <div>
                    {{ partial "summary.html" . }}
                  </div>
              </li>
          {{ end }}
          </ul>
      {{ partial "pagination.html" . }}
  </main>
{{ end }}

示例：使用 .Site.GetPage

​ .Site.GetPage 的示例假设有以下项目目录结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

.
└── content
    ├── blog
    │   ├── _index.md # "title: My Hugo Blog" in the front matter
    │   ├── post-1.md
    │   ├── post-2.md
    │   └── post-3.md
    └── events #Note there is no _index.md file in "events"
        ├── event-1.md
        └── event-2.md

​ 如果没有找到 _index.md 页面，则 .Site.GetPage 将返回 nil。因此，如果 content/blog/_index.md 不存在，则该模板将输出该章节的名称：

1

<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>

​ 由于 blog 有一个带有前置元数据的章节索引页位于 content/blog/_index.md，因此上述代码将返回以下结果：

1

<h1>My Hugo Blog</h1>

​ 但如果我们尝试在 events 章节使用相同的代码，则 Hugo 会默认使用章节标题，因为没有 content/events/_index.md 可供提取内容和前置元数据：

1

<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>

​ 然后返回以下结果：

1

<h1>Events</h1>

另请参阅

• .GetPage
• 内容章节
• 内容类型
• Hugo 中的内容列表
• 菜单模板

10 - 单页模板

Single Page Templates - 单页模板

​ 在 Hugo 中，内容的主要视图是单个视图。Hugo 会为每个 Markdown 文件提供相应的单个模板进行渲染。

单页模板查找顺序

​ 请参阅模板查找。

单页模板示例

​ 内容页面的类型是 page，因此可以在它们的模板中使用所有 页面变量 和 站点变量。

posts/single.html

​ 这个单页模板使用了 Hugo 的 基础模板、.Format 函数 来处理日期、.WordCount 页面变量 以及遍历单一内容的特定分类法。with 也用来检查是否在前置元数据中设置了分类法。

layouts/posts/single.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{{ define "main" }}

<section id="main">
  <h1 id="title">{{ .Title }}</h1>
  <div>
    <article id="content">
      {{ .Content }}
    </article>
  </div>
</section>
<aside id="meta">
  <div>
  <section>
    <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
    <h5 id="wordcount"> {{ .WordCount }} Words </h5>
  </section>
    {{ with .GetTerms "topics" }}
      <ul id="topics">
        {{ range . }}
          <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
        {{ end }}
      </ul>
    {{ end }}
    {{ with .GetTerms "tags" }}
      <ul id="tags">
        {{ range . }}
          <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
        {{ end }}
      </ul>
    {{ end }}
  </div>
  <div>
    {{ with .PrevInSection }}
      <a class="previous" href="{{ .Permalink }}"> {{ .Title }}</a>
    {{ end }}
    {{ with .NextInSection }}
      <a class="next" href="{{ .Permalink }}"> {{ .Title }}</a>
    {{ end }}
  </div>
</aside>
{{ end }}