自定义输出格式

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模板