模板

分类模板

Hugo 支持用户定义的内容分组称为分类。分类是表达内容之间的逻辑关系的分类方法。如果您对 Hugo 如何利用此强大功能感到陌生，请参阅 内容管理中的分类。

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

  • 以 分类列表模板 的方式排序与分类词汇相关联的内容
  • 以 分类词汇模板 的方式排序分类词汇的显示方式
  • 在 [单页面模板] 中列出单个内容的分类词汇

分类列表模板

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

分类列表模板查找顺序

请参阅 模板查找顺序。

分类词汇模板

分类词汇模板查找顺序

请参阅 模板查找顺序。

分类方法

分类是一个 map[string]WeightedPages。

.Get TERM
返回给定词汇的 WeightedPages。例如：; site.Taxonomies.tags.Get "tag-a"。
.Count TERM
分配给给定词汇的内容的数量。例如：
site.Taxonomies.tags.Count "tag-a"。
.Alphabetical
按词汇顺序返回 OrderedTaxonomy（切片）。
.ByCount
按分类中的条目数量返回 OrderedTaxonomy（切片）。
.Reverse
以相反的顺序返回 OrderedTaxonomy（切片）。必须与 OrderedTaxonomy 一起使用。

OrderedTaxonomy

由于映射是无序的，OrderedTaxonomy 是一个具有定义顺序的特殊结构。

[]struct {
    Name          string
    WeightedPages WeightedPages
}

切片的每个元素有：

.Term
使用的词汇。
.WeightedPages
一个 Weighted Page 的切片。
.Count
分配给此词汇的内容数量。
.Page
返回此词汇的页面引用。
.Pages
分配给此词汇的所有页面。此页面可用于所有 列表方法。

WeightedPages

WeightedPages 只是 WeightedPage 的切片。

type WeightedPages []WeightedPage
.Count
分配给该词汇的内容数。
.Page
返回此词汇的页面引用。
.Pages
返回一个页面切片，然后可以使用任何 列表方法 对其排序。

在分类词汇模板中显示自定义元数据

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

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

排序分类

分类可以按照字母顺序键或分配给该键的内容的数量进行排序。

按字母顺序排序示例 

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

排序分类中的内容

Hugo 使用 date 和 weight 来对分类中的内容进行排序。

Hugo 的每个内容可以选择分配日期。它还可以为其分配每个分类的权重。

在分类中迭代内容时，默认排序与部分和列表页面使用的排序相同：首先按权重，然后按日期排序。这意味着如果两个内容的权重相同，则较新的内容将首先显示。

任何内容的默认权重为 0。零意味着“没有权重”，而不是“权重为 0”。

因此，零权重的内容受到特殊处理：如果两个页面的权重不相等，并且其中一个页面的权重为零，则始终在另一个页面之后显示零权重的页面，而不管其他页面的权重如何。因此，应谨慎使用零权重：例如，如果正负权重都用于在两个方向上扩展序列，则零权重的页面将不会显示在列表中间，而是显示在末尾。

分配权重

可以为每个分配给的分类分配内容的权重。

content/example.md
      
---
categories:
- d
categories_weight: 44
tags:
- a
- b
- c
tags_weight: 22
title: Example
---
+++
categories = ['d']
categories_weight = 44
tags = ['a', 'b', 'c']
tags_weight = 22
title = 'Example'
+++
{
   "categories": [
      "d"
   ],
   "categories_weight": 44,
   "tags": [
      "a",
      "b",
      "c"
   ],
   "tags_weight": 22,
   "title": "Example"
}

约定为 分类名_weight。

在上面的示例中，此内容的权重为 22，在呈现分配给 ’tag’ 分类的 ‘a’、‘b’ 和 ‘c’ 值的页面时应用排序。

它还在呈现 ’d’ 分类时分配了权重为 44。

有了此功能，相同的内容可以在不同的分类中以不同的位置显示。

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

在使用分类时，将需要提供两个不同的模板。

这两个模板在模板部分有详细介绍。

list template 是用于在单个 html 页面中呈现多个内容的任何模板。此模板将用于生成所有自动生成的分类页面。

taxonomy template 是用于生成给定模板的词汇列表的模板。

除了 Hugo 使用 列表模板 自动创建的分类页面之外，还有四种常见的方式可以在分类中显示数据：

  1. 对于给定的内容，可以列出所附的词汇
  2. 对于给定的内容，可以列出具有相同词汇的其他内容
  3. 可以列出分类的所有词汇
  4. 可以列出所有分类（以及其词汇）

列出分配给页面的词汇

使用 .Page.GetTerms 方法来列出分配给页面的词汇。

要呈现无序列表：

{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
  <p>{{ (site.GetPage $taxonomy).LinkTitle }}:</p>
  <ul>
    {{ range . }}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ end }}
  </ul>
{{ end }}

要呈现逗号分隔的列表：

{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
  <p>
    {{ (site.GetPage $taxonomy).LinkTitle }}:
    {{ range $k, $_ := . -}}
      {{ if $k }}, {{ end }}
      <a href="{{ .RelPermalink }}">{{ .Title }}</a>
    {{- end }}
  </p>
{{ end }}

列出具有相同分类词汇的内容

如果您将分类用于类似一系列帖子的内容，则可以列出与相同分类关联的单个页面。这也是显示相关内容的快速粗略方法：

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

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

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

这在侧边栏中非常有用，作为“特色内容”。您甚至可以通过为内容分配不同的词汇来拥有“特色内容”的不同部分。

示例：分组“特色”内容 

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

显示网站的分类

如果您想要显示站点分类键的列表，可以从访问每个页面上可用的.Site变量中检索它们。

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

下面的示例显示站点标签分类中的所有词汇：

示例：列出所有网站标签 

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

示例：列出所有分类、词汇和分配的内容

此示例将列出所有分类及其词汇，以及分配给每个词汇的所有内容。

layouts/partials/all-taxonomies.html
<ul>
  {{ range $taxonomy, $terms := site.Taxonomies }}
    <li>
      {{ with site.GetPage $taxonomy }}
        <a href="{{ .RelPermalink }}">{{ .Title }}</a>
      {{ end }}
      <ul>
        {{ range $term, $weightedPages := $terms }}
          <li>
            <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
            <ul>
              {{ range $weightedPages }}
                <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
              {{ end }}
            </ul>
          </li>
        {{ end }}
      </ul>
    </li>
  {{ end }}
</ul>

对于分类的 .Site.GetPage

因为分类是列表，可以使用 .GetPage 函数 使用简洁的语法得到与特定分类词汇关联的所有页面。以下只是一个对站点上所有标签进行迭代的示例，并链接到每个标签的单独分类页面，而无需使用"List All Site Tags 示例中的更易坏的 URL 构造：

See also

Last updated: November 23, 2023: first release (332dc4cd7)
Improve this page