自定义输出格式

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

媒体类型

媒体类型（以前称为 MIME 类型）是互联网上传输的文件格式和格式内容的两个部分标识符。

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

注意

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

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

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

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

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

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

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

mediaTypes:
  text/html:
    suffixes:
    - htm
outputFormats:
  html:
    mediaType: text/html

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

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

输出格式定义

给定一个媒体类型和一些额外的配置，您将获得一个输出格式。

这是 Hugo 内置输出格式的完整集合

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

要添加或修改输出格式，请在您的站点的配置文件中的 outputFormats 部分中定义它，可以针对所有站点或针对给定的语言。

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

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

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

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

配置输出格式

配置输出格式时使用以下参数

baseName

（string）发布文件的基本名称。默认为 index。

isHTML

（bool）如果为 true，则将输出格式分类为 HTML。Hugo 使用此值来确定何时创建别名重定向，何时注入 LiveReload 脚本等。默认为 false。

isPlainText

（bool）如果为 true，Hugo 将使用 Go 的 text/template 包而不是 html/template 包来解析此输出格式的模板。默认为 false。

mediaType

（string）发布文件的 媒体类型。这必须与已定义的媒体类型匹配，无论是内置的还是自定义的。

notAlternative

（bool）如果为 true，则将此输出格式从 Page 对象上的 AlternativeOutputFormats 方法返回的值中排除。默认为 false。

noUgly

（bool）如果为 true，则当站点配置中的 uglyURLs 为 true 时，禁用此输出格式的丑陋 URL。默认为 false。

path

（string）包含发布文件的目录的路径，相对于发布目录的根目录。

permalinkable

（bool）如果为 true，Page 对象上的 Permalink 和 RelPermalink 方法将返回渲染输出格式，而不是主输出格式（参见下文）。默认情况下为 html 和 amp 输出格式启用。默认为 false。

protocol

（string）此输出格式的 URL 协议（方案）。例如，https:// 或 webcal://。默认为站点配置中 baseURL 参数的方案，通常为 https://。

rel

（string）如果提供，则在模板中迭代输出格式时，可以将此值分配给 link 元素中的 rel 属性。默认为 alternate。

root

（bool）如果为 true，文件将发布到发布目录的根目录。默认为 false。

ugly

（bool）如果为 true，则当站点配置中的 uglyURLs 为 false 时，启用此输出格式的丑陋 URL。默认为 false。

weight

（int）当设置为非零值时，Hugo 会将 weight 作为对输出格式进行排序的第一个标准，如果 weight 相等，则回退到输出格式的名称。较轻的项目会浮到顶部，而较重的项目会沉到底部。Hugo 会根据排序顺序依次渲染输出格式。

页面的输出格式

Hugo 中的一个 Page 可以在文件系统中渲染为多种输出格式。

默认输出格式

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

outputs:
  home:
  - html
  - rss
  page:
  - html
  rss:
  - rss
  section:
  - html
  - rss
  taxonomy:
  - html
  - rss
  term:
  - html
  - rss

[outputs]
  home = ['html', 'rss']
  page = ['html']
  rss = ['rss']
  section = ['html', 'rss']
  taxonomy = ['html', 'rss']
  term = ['html', 'rss']

{
   "outputs": {
      "home": [
         "html",
         "rss"
      ],
      "page": [
         "html"
      ],
      "rss": [
         "rss"
      ],
      "section": [
         "html",
         "rss"
      ],
      "taxonomy": [
         "html",
         "rss"
      ],
      "term": [
         "html",
         "rss"
      ]
   }
}

自定义输出格式

可以通过在 Page 前端元数据或站点配置（针对所有站点或每个语言）中定义输出格式的 outputs 列表来更改此设置。

来自站点配置文件的示例

outputs:
  home:
  - html
  - amp
  - rss
  page:
  - html

[outputs]
  home = ['html', 'amp', 'rss']
  page = ['html']

{
   "outputs": {
      "home": [
         "html",
         "amp",
         "rss"
      ],
      "page": [
         "html"
      ]
   }
}

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

• outputs 的定义是针对每个页面 Kind 的。
• 名称（例如 html、amp）必须与已定义的输出格式的 name 匹配，并且可以在前端元数据中按页面覆盖。

以下是一个内容文件中前端元数据的示例，该示例定义了渲染的 Page 的输出格式

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

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

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

列出输出格式

每个 Page 对象都有一个 OutputFormats 方法（所有格式，包括当前格式）和一个 AlternativeOutputFormats 方法，后者对于在站点的 <head> 中创建 link rel 列表很有用

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

链接到输出格式

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

来自 single.json.json

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

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

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

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

从内容文件中，可以使用 ref 或 relref 短代码

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

输出格式的模板

每个输出格式都需要一个符合模板查找顺序的相应模板。Hugo 在选择模板时会考虑输出格式和后缀。

例如，要为首页生成 JSON 文件，最高优先级的模板是 layouts/index.json.json。

如果可能，Hugo 现在还会检测 partials 的媒体类型和输出格式，并使用该信息来决定是否应将 partials 解析为纯文本模板。

Hugo 将查找给定的名称，因此您可以随意命名。但是，如果您希望将其视为纯文本，则应使用文件后缀，并在需要时使用输出格式的名称。模式如下：

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

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

{{ partial "mytextpartial.csv" . }}