Hugo框架中文文档模板标签分类模板

Hugo支持用户定义的内容分组，也就是taxonomies 标签分类。标签是展示内容逻辑联系的分类. 参考内容管理中标签, 如果您不熟悉Hugo使用这个强大特性的方式。

Hugo提供了在项目模板中使用标签的多种方式::

对展示在taxonomy list template中的一个标签条目相关的内容的排序
对展示在taxonomy terms template中的条目排序方式的支持
在单一页面模板single page template中对单一页面内容的标签条目列表展示

标签列表模板 Taxonomy List Templates

标签列表模板是list页面，因此可以具有list pages的所有变量,可以访问list pages的所有方法.

标签列表模板查询顺序 Taxonomy List Template Lookup Order

参考Template Lookup.

标签条目模板

标签条目模板查询顺序 Taxonomy Terms Templates Lookup Order

参考 Template Lookup.

方法 Taxonomy Methods

一个标签是一个 map[string]WeightedPages 以字符串为键、以带有权重的页面集合为值的映射字典.

.Get(term): 返回条目相关的权重页面
.Count(term): 返回条目相关的内容数量
.Alphabetical: 返回按条目排序的有序标签(slice)
.ByCount: 返回按条目数目排序的有序标签(slice)
.Reverse: 返回有序标签列表的倒序。必须和有序标签使用。

排序的标签 OrderedTaxonomy

由于Maps是无序的、一个有序的标签集合是具有指定顺序的特殊结构.

1
2
3
4
[]struct {
    Name          string
    WeightedPages WeightedPages
}

每个slice的元素都具有:

.Term: 标签条目
.WeightedPages: 有权重页面的slice
.Count: 赋予本条目的内容的数目.
.Pages: 所有赋值了本条目的页面。可以访问list methods 的所有方法.

权重页面 WeightedPages

权重页面WeightedPages是权重页面WeightedPage的slice

1
type WeightedPages []WeightedPage

.Count(term): 赋值标签条目的内容的数量
.Pages: 返回页面的slice, 此slice随后可以通过list methods的任何函数排序.

在标签条目模板中展示定制元数据

如果希望对每个标签条目展示定制的元数据, 您需要为此条目创建页面/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>

标签排序 Order Taxonomies

标签可以按照键的字母顺序或者赋予标签值的内容的数量来排序:

按字母顺序排序的例子 Order Alphabetically Example

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

标签内容排序 Order Content within Taxonomies

在标签内容内部可以使用 date 和 weight 来排序

Hugo中每个内容可以可选择性的设置一个日期。同时也可以对赋予的每个标签设置一个weight权重值.

在标签内遍历内容时, 默认的排序同区块和list页面的排序规则一样, 首先按weight, 然后按日期. 这意味着如果两个内容具有相同的标签权重, 那么日期上最近的内容会先展示.

任何内容的默认权重是0. 零表示"不具有权重", 而不是"具有权重值为0".

零权重的内容会被特殊对待: 如果两个页面具有不同的权重, 其中一个为零, 那么零权重的页面总是会在另一个页面的后面出现, 不论另一个页面的权重是多少. 因此零权重的应该谨慎使用: 比如, 如果正数和负数权重被用在一个序列的双向扩展中, 零权重的页面不会出现在list的中间，而是出现在最后(这不和常理).

赋值权重 Assign Weight

内容可以为每个赋予的标签赋值

1
2
3
4
5
6
7
8
+++
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
title = "foo"
categories_weight = 44
+++
Front Matter with weighted tags and categories

赋值惯例是 标签名称_weight

上例中，这个页面内容在赋值了标签值"a", “b” 和 “c"的页面呈现时, 排序所使用的权重是22.

同时在category d的呈现时使用的的权重是44.

在不同标签分类中，同一篇内容会出现在不同的位置.

当前标签仅仅支持默认的内容排序,也就是先按weight然后按日期.

使用标签分类您需要提供两种不同的模板

两种模板在模板部分都有详尽的描述

列表模板是指用来在单一html页面中展示多个内容的任何模板.这个模板被用来生成全部的自动生成的标签页面。

标签条目模板是用来生成标签条目list的任何模板.

在Hugo自动创建的标签页之外, 还可以有四种使用list templates的常见方式来展示标签的数据:

对指定内容, 可以列出所有的赋予的标签条目 For a given piece of content, you can list the terms attached
对指定内容，可以列出具有相同标签条目的其他内容 For a given piece of content, you can list other content with the same term
可以列出一个标签分类的所有条目 You can list all terms for a taxonomy
可以列出所有标签分类(和他们的条目)You can list all taxonomies (with their terms)

展示页面的内容标签

在内容模板中，您可能希望展示内容被赋予的标签条目

由于我们使用前言设定来定义内容的标签, 赋予每个内容的标签位于通常位置 (比如, .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 template function作为短代码,

具有相同标签条目的内容列表 List Content with the Same Taxonomy Term

如果对一系列posts应用了相同的标签, 您可以列出和这个相同标签关联的单独页面的list。这也是显示相关内容的快速方法,虽然方法丑陋了点。

例子: 显示同一系列中的内容

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

对给定标签列出所有内容 List All content in a Given taxonomy

这个在提供侧边栏的功能比如 “featured content”时很有用。通过给内容赋予不同的条目,甚至可以有多个不同的 “featured content” 部分.

例子: “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>

呈现站点的标签 Render a Site’s Taxonomies

如果需要显示站点标签的所有key, 可以从每个页面可以访问的.Site variable来获取。

可以采取标签云的形式，或者菜单、或者就是一个简单的列表。

下面例子展示了站点tags标签的所有条目:

例子: 所有标签的列表

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

例子: 列出所有标签、条目、和被赋值的内容

这个例子list所有的标签，他们的条目，以及被赋予条目的所有内容

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
23

<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` for Taxonomies

因为taxonomies是list,所以可以使用.GetPage 函数以紧凑的形式获得与特定条目关联的所有页面。下例遍历站点的tags的完整list, 链接到每个条目独立的标签页，不需要用上面例子“List All Site Tags” example above中的脆弱的URL构建方式.

links-to-all-tags.html

1
2
3
4
5
6
7
8
9

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

Contents