Hugo框架中文文档 Templates模板 定制输出格式

本文档如何正确配置站点的媒体类型和输出格式, 以及为定制输出创建模板的路径

媒体类型

媒体类型 (也称为 MIME type 以及 内容类型content type) 是两部分组成的文件格式标志符, 也是网络上传输的内容格式。

这是Hugo内置的媒体类型的全部集合:

注意:

• 可以添加定制媒体类型或者改变默认的媒体类型;比如，可以改变 text/html 的后缀为asp.
• 后缀值会用于Hugo中对应的媒体类型的URLs和文件名称.
• Type 是定义新的或者定制 Output Formats (见下面)必须使用的标志符.
• 媒体类型的全部集合在Hugo的内置开发服务器中注册，以确保可以被浏览器识别

添加或者修改一个媒体类型，请在site configuration中mediaTypes 部分添加或修改, 针对所有站点或者某给定语言.

1
2
3
4
5
6
7

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

1
2
3
4
5

[mediaTypes]
  [mediaTypes."text/enriched"]
    suffixes = ["enr"]
  [mediaTypes."text/html"]
    suffixes = ["asp"]

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

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

上面例子添加了一个媒体类型,text/enriched, 同时改变了内置 text/html 媒体类型的后缀.

注意: 这些媒体类型是为 您的输出格式 而配置的. 如果想重新定义Hugo的默认的输出格式中一个(比如HTML), 您也需要定义媒体类型。 下面配置改变了 HTML 输出格式从 默认的html 修改为 htm:

1
2
3
4
5
6
7
8

[mediaTypes]
[mediaTypes."text/html"]
suffixes = ["htm"]

# Redefine HTML to update its media type.
[outputFormats]
[outputFormats.HTML]
mediaType = "text/html"

注意 为上面代码工作, 您站点配置文件中需要一个outputs 定义.

输出格式定义 Output Format Definitions

给定一个媒体类型，添加一些配置，您就配置好了输出格式

这里是Hugo内置的输出格式的全部集合:

• 每个页面能够以您需要的任意多输出格式输出, 而且您可以定义任意数量的输出格式， 只要他们解析到文件系统的唯一路径.上表中,最佳的例子是AMP 和 HTML 对比。AMP的路径为amp, 所以它不覆盖HTML版本, 进而我们可以访问 /index.html 和 /amp/index.html.
• MediaType必须和已经定义的某个媒体类型的Type匹配
• 可以定义新的输出格式，或者重定义内置的输出格式，比如想将AMP页面置于不同路径.

添加或者修改一个输出类型，请在site configuration中outputFormats 部分添加或修改, 针对所有站点或者某给定语言.

1
2
3
4
5
6

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

1
2
3
4
5
6

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

上面例子是想象出来的, 如果作为baseURL为https://example.org的站点的首页，当通过URL bep://example.org/myindex.enr访问时, Hugo会生成一个朴素的文本文件主页.

配置输出格式

下面是输出格式的配置选项的全部列表以及他们的默认值:

name

输出格式的标志符号. 用来定义页面的输出格式.

mediaType

必须与已经定义的媒体类型的Type匹配.

path

保存输出文件的sub path.

baseName

文件名称列表(首页等)的基础文件名称 默认值: index.

rel

可以用来在link 标签中创建 rel. 缺省值: alternate.

protocol

替换输出格式的baseURL中的"http://" 或者 “https://”.

isPlainText

如果为真, 将使用Go语言的朴素文本解析器解析模板. 缺省值: false.

isHTML

仅仅在类似HTML格式的情景中有关,比如 页面别名.

noUgly :当站点设置uglyURLs为true时, 关闭ugly URLs. 缺省值: false.

notAlternative

如果在页面(如Css)的AlternativeOutputFormats 格式列表中包含它无意义的化，设置这个变量为真。 注意这里我们使用条目 alternative 而不是alternate, 因为它没有必要会替换其他格式. 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. 缺省值: false. ??

permalinkable

使得 .Permalink and .RelPermalink 返回呈现的输出格式而不是main(see below). 对HTML和AMP默认是启用的。 make .Permalink and .RelPermalink return the rendering Output Format rather than main (see below). This is enabled by default for HTML and AMP. 缺省值: false.

页面的输出格式

Hugo中页面可以在文件系统中呈现出多种输出格式。

默认的输出格式

每一页都有 Kind 属性, 默认的输出格式基于这个kind属性

定制输出格式 Customizing Output Formats

在页面的前言设定或者网站配置文件(对所有站点或者每个语言)中定义输出格式的outputs列表可以定制输出格式.

站点配置的例子:

1
2
3
4
5
6
7

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

1
2
3

[outputs]
  home = ["HTML", "AMP", "RSS"]
  page = ["HTML"]

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

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

注意上面例子中, section, taxonomy 和 term 的输出格式 仍然是它们的默认值["HTML", "RSS"].

New in v0.73.0 We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your outputs section.

• 输出的定义是针对每一个 Page Kind (page, home, section, taxonomy, or term).
• 输出格式的名称(如 HTML AMP)必须和定义的输出格式的Name匹配The names.
• 这些名称是大小写无关的.
• 可以在内容页面的前言设定重载这个设置.

下面是一个内容文件的YAML前言设定的例子，定义了输出的Page的输出格式:

1
2
3
4
5
6
7

---
date: "2016-03-19"
outputs:
- html
- amp
- json
---

##输出格式的列表

每个页面都有.OutputFormats (所有格式, 包含当前的格式) 和 .AlternativeOutputFormats变量, 后者有助于在站点的<head>创建link rel的list:

1
2
3

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

输出格式的链接

页面的.Permalink 和 .RelPermalink 会返回页面定义的输出格式中第一个(通常是HTML, 如果没有定义其他的)。这个调用它们的模板文件无关。

from single.json.json:

1
2
3
4

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

为了上面代码段返回的是当前模板文件的输出格式, 给定的输出格式应该设置permalinkable为true.

同上面一样的模板文件，设置了json输出格式的permalinkable为真:

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的对应的模板查询顺序. 表内例子都可以:

• 使用基础模板base template.
• 包含局部部分模板partial templates

Hugo的现在版本会检测部分模板的媒体类型和输出格式，如果可能的话，并且使用这些信息决定部分模板是否可以解析为纯文本模板。

Hugo会查找给定的名称，所以可以随意命名。但是如果你想文件被当成纯文本处理, 那么应该使用文件后缀，如果需要的化，还有输出格式的名称。 模式如下:

1

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

下面例子的partial部分是一个纯文本模板(输出格式是CSV, 而且由于这是唯一具有后缀csv的输出格式, 我们不需要包含输出格式的Name):

1

{{ partial "mytextpartial.csv" . }}