自定义输出格式

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

媒体类型

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

下面是Hugo内置的媒体类型的全套列表:

注意:

• 可以添加自定义媒体类型或更改默认值。例如，如果要将text/html的后缀更改为asp。
• “suffixes"是该媒体类型在Hugo中用于URL和文件名的值。
• “Type"是定义新/自定义"Output Formats"时必须使用的标识符。
• 完整的媒体类型集将在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"
      }
   }
}

注意，为了使上述内容正常工作，还需要在您的站点配置中添加一个outputs定义。

输出格式定义

根据媒体类型和其他一些配置，您可以得到一个输出格式。

下面是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的网站上的主页，它将生成一个具有URLbep：//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

如果在站点中将uglyURLs设置为true，则用于关闭丑陋的URL。默认值： false。

notAlternative

如果在Page上的AlternativeOutputFormats格式列表中不包含此格式，则启用。请注意，此处使用的术语为_代替_，而不是_替换_，因为它不一定替换另一个格式。默认值： false。

permalinkable

使.Permalink和.RelPermalink返回渲染输出格式的内容，而不是主要输出格式（见下文）。对于HTML和AMP默认启用。默认值： false。

weight

如果将其设置为非零值，将用作第一个排序标准。

页面的输出格式

在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 shortcodes来从内容文件中创建链接：

[那个好东西]({{< ref "blog/neat.md" "amp" >}})
[谁]({{< relref "about.md#who" "amp" >}})

输出格式的模板

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

例如，要为主页生成一个JSON文件，具有最高特定性的模板是layouts/index.json.json。

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

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

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

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

{{ partial "mytextpartial.csv" . }}