自定义输出格式

本页面描述如何使用媒体类型和输出格式正确配置您的站点，以及在哪里为自定义输出创建模板。

媒体类型

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

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

注意：

• 可以添加自定义媒体类型或更改默认值；例如，如果您想将 text/html 的后缀更改为 asp 。
• Suffixes 是 Hugo 中将用于该媒体类型的 URL 和文件名。
• Type 是定义新的/自定义 输出格式(见下文)时必须使用的标识符。
• 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 时，将为此输出格式启用 uglyURLs。默认为 false 。

weight

(int) 当设置为非零值时，Hugo 使用 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 现在还将检测媒体类型和输出格式的部分，如果可能的话，并使用该信息来决定是否应该将部分解析为纯文本模板。

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

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

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

{{ partial "mytextpartial.csv" . }}