HUGO
Menu
GitHub 87548 stars Mastodon

Hugo 配置输出格式

Hugo 配置输出格式。

output format（输出格式）是一组设置，定义 Hugo 在构建网站时如何渲染文件。例如，html、json ?rss 是内置输出格式。您可以创建多个输出格式，并根据 page kind（页面类型）控制它们的生成，或通过为特定页面启用一个或多个输出格式

您可以根据需要以多种格式输出页面。定义无限数量的输出格式，只要它们各自解析为唯一的文件系统路径。

这是默认输出格式配置的表格形式：

type mediaType weight baseName isHTML isPlainText noUgly notAlternative path permalinkable protocol rel root ugly
404 text/html 0 true false false true true false true
alias text/html 0 true false false false false false true
amp text/html 0 index true false false false amp true amphtml false false
calendar text/calendar 0 index false true false false false webcal:// alternate false false
css text/css 0 styles false true false true false stylesheet false false
csv text/csv 0 index false true false false false alternate false false
gotmpl text/x-gotmpl 0 false true false true false false false
html text/html 10 index true false false false true canonical false false
json application/json 0 index false true false false false alternate false false
markdown text/markdown 0 index false true false false false alternate false false
robots text/plain 0 robots false true false false false alternate true false
rss application/rss+xml 0 index false false true false false alternate false false
sitemap application/xml 0 sitemap false false false false false sitemap false true
sitemapindex application/xml 0 sitemap false false false false false sitemap true true
webappmanifest application/manifest+json 0 manifest false true false true false manifest false false

默认配置

以下是与上表匹配的默认配置：

outputFormats:
  '404':
    baseName: ''
    isHTML: true
    isPlainText: false
    mediaType: text/html
    noUgly: false
    notAlternative: true
    path: ''
    permalinkable: true
    protocol: ''
    rel: ''
    root: false
    ugly: true
    weight: 0
  alias:
    baseName: ''
    isHTML: true
    isPlainText: false
    mediaType: text/html
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: ''
    root: false
    ugly: true
    weight: 0
  amp:
    baseName: index
    isHTML: true
    isPlainText: false
    mediaType: text/html
    noUgly: false
    notAlternative: false
    path: amp
    permalinkable: true
    protocol: ''
    rel: amphtml
    root: false
    ugly: false
    weight: 0
  calendar:
    baseName: index
    isHTML: false
    isPlainText: true
    mediaType: text/calendar
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: webcal://
    rel: alternate
    root: false
    ugly: false
    weight: 0
  css:
    baseName: styles
    isHTML: false
    isPlainText: true
    mediaType: text/css
    noUgly: false
    notAlternative: true
    path: ''
    permalinkable: false
    protocol: ''
    rel: stylesheet
    root: false
    ugly: false
    weight: 0
  csv:
    baseName: index
    isHTML: false
    isPlainText: true
    mediaType: text/csv
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: alternate
    root: false
    ugly: false
    weight: 0
  gotmpl:
    baseName: ''
    isHTML: false
    isPlainText: true
    mediaType: text/x-gotmpl
    noUgly: false
    notAlternative: true
    path: ''
    permalinkable: false
    protocol: ''
    rel: ''
    root: false
    ugly: false
    weight: 0
  html:
    baseName: index
    isHTML: true
    isPlainText: false
    mediaType: text/html
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: true
    protocol: ''
    rel: canonical
    root: false
    ugly: false
    weight: 10
  json:
    baseName: index
    isHTML: false
    isPlainText: true
    mediaType: application/json
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: alternate
    root: false
    ugly: false
    weight: 0
  markdown:
    baseName: index
    isHTML: false
    isPlainText: true
    mediaType: text/markdown
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: alternate
    root: false
    ugly: false
    weight: 0
  robots:
    baseName: robots
    isHTML: false
    isPlainText: true
    mediaType: text/plain
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: alternate
    root: true
    ugly: false
    weight: 0
  rss:
    baseName: index
    isHTML: false
    isPlainText: false
    mediaType: application/rss+xml
    noUgly: true
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: alternate
    root: false
    ugly: false
    weight: 0
  sitemap:
    baseName: sitemap
    isHTML: false
    isPlainText: false
    mediaType: application/xml
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: sitemap
    root: false
    ugly: true
    weight: 0
  sitemapindex:
    baseName: sitemap
    isHTML: false
    isPlainText: false
    mediaType: application/xml
    noUgly: false
    notAlternative: false
    path: ''
    permalinkable: false
    protocol: ''
    rel: sitemap
    root: true
    ugly: true
    weight: 0
  webappmanifest:
    baseName: manifest
    isHTML: false
    isPlainText: true
    mediaType: application/manifest+json
    noUgly: false
    notAlternative: true
    path: ''
    permalinkable: false
    protocol: ''
    rel: manifest
    root: false
    ugly: false
    weight: 0

[outputFormats]
  [outputFormats.404]
    baseName = ''
    isHTML = true
    isPlainText = false
    mediaType = 'text/html'
    noUgly = false
    notAlternative = true
    path = ''
    permalinkable = true
    protocol = ''
    rel = ''
    root = false
    ugly = true
    weight = 0
  [outputFormats.alias]
    baseName = ''
    isHTML = true
    isPlainText = false
    mediaType = 'text/html'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = ''
    root = false
    ugly = true
    weight = 0
  [outputFormats.amp]
    baseName = 'index'
    isHTML = true
    isPlainText = false
    mediaType = 'text/html'
    noUgly = false
    notAlternative = false
    path = 'amp'
    permalinkable = true
    protocol = ''
    rel = 'amphtml'
    root = false
    ugly = false
    weight = 0
  [outputFormats.calendar]
    baseName = 'index'
    isHTML = false
    isPlainText = true
    mediaType = 'text/calendar'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = 'webcal://'
    rel = 'alternate'
    root = false
    ugly = false
    weight = 0
  [outputFormats.css]
    baseName = 'styles'
    isHTML = false
    isPlainText = true
    mediaType = 'text/css'
    noUgly = false
    notAlternative = true
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'stylesheet'
    root = false
    ugly = false
    weight = 0
  [outputFormats.csv]
    baseName = 'index'
    isHTML = false
    isPlainText = true
    mediaType = 'text/csv'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'alternate'
    root = false
    ugly = false
    weight = 0
  [outputFormats.gotmpl]
    baseName = ''
    isHTML = false
    isPlainText = true
    mediaType = 'text/x-gotmpl'
    noUgly = false
    notAlternative = true
    path = ''
    permalinkable = false
    protocol = ''
    rel = ''
    root = false
    ugly = false
    weight = 0
  [outputFormats.html]
    baseName = 'index'
    isHTML = true
    isPlainText = false
    mediaType = 'text/html'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = true
    protocol = ''
    rel = 'canonical'
    root = false
    ugly = false
    weight = 10
  [outputFormats.json]
    baseName = 'index'
    isHTML = false
    isPlainText = true
    mediaType = 'application/json'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'alternate'
    root = false
    ugly = false
    weight = 0
  [outputFormats.markdown]
    baseName = 'index'
    isHTML = false
    isPlainText = true
    mediaType = 'text/markdown'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'alternate'
    root = false
    ugly = false
    weight = 0
  [outputFormats.robots]
    baseName = 'robots'
    isHTML = false
    isPlainText = true
    mediaType = 'text/plain'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'alternate'
    root = true
    ugly = false
    weight = 0
  [outputFormats.rss]
    baseName = 'index'
    isHTML = false
    isPlainText = false
    mediaType = 'application/rss+xml'
    noUgly = true
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'alternate'
    root = false
    ugly = false
    weight = 0
  [outputFormats.sitemap]
    baseName = 'sitemap'
    isHTML = false
    isPlainText = false
    mediaType = 'application/xml'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'sitemap'
    root = false
    ugly = true
    weight = 0
  [outputFormats.sitemapindex]
    baseName = 'sitemap'
    isHTML = false
    isPlainText = false
    mediaType = 'application/xml'
    noUgly = false
    notAlternative = false
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'sitemap'
    root = true
    ugly = true
    weight = 0
  [outputFormats.webappmanifest]
    baseName = 'manifest'
    isHTML = false
    isPlainText = true
    mediaType = 'application/manifest+json'
    noUgly = false
    notAlternative = true
    path = ''
    permalinkable = false
    protocol = ''
    rel = 'manifest'
    root = false
    ugly = false
    weight = 0

{
   "outputFormats": {
      "404": {
         "baseName": "",
         "isHTML": true,
         "isPlainText": false,
         "mediaType": "text/html",
         "noUgly": false,
         "notAlternative": true,
         "path": "",
         "permalinkable": true,
         "protocol": "",
         "rel": "",
         "root": false,
         "ugly": true,
         "weight": 0
      },
      "alias": {
         "baseName": "",
         "isHTML": true,
         "isPlainText": false,
         "mediaType": "text/html",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "",
         "root": false,
         "ugly": true,
         "weight": 0
      },
      "amp": {
         "baseName": "index",
         "isHTML": true,
         "isPlainText": false,
         "mediaType": "text/html",
         "noUgly": false,
         "notAlternative": false,
         "path": "amp",
         "permalinkable": true,
         "protocol": "",
         "rel": "amphtml",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "calendar": {
         "baseName": "index",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/calendar",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "webcal://",
         "rel": "alternate",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "css": {
         "baseName": "styles",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/css",
         "noUgly": false,
         "notAlternative": true,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "stylesheet",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "csv": {
         "baseName": "index",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/csv",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "alternate",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "gotmpl": {
         "baseName": "",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/x-gotmpl",
         "noUgly": false,
         "notAlternative": true,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "html": {
         "baseName": "index",
         "isHTML": true,
         "isPlainText": false,
         "mediaType": "text/html",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": true,
         "protocol": "",
         "rel": "canonical",
         "root": false,
         "ugly": false,
         "weight": 10
      },
      "json": {
         "baseName": "index",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "application/json",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "alternate",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "markdown": {
         "baseName": "index",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/markdown",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "alternate",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "robots": {
         "baseName": "robots",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "text/plain",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "alternate",
         "root": true,
         "ugly": false,
         "weight": 0
      },
      "rss": {
         "baseName": "index",
         "isHTML": false,
         "isPlainText": false,
         "mediaType": "application/rss+xml",
         "noUgly": true,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "alternate",
         "root": false,
         "ugly": false,
         "weight": 0
      },
      "sitemap": {
         "baseName": "sitemap",
         "isHTML": false,
         "isPlainText": false,
         "mediaType": "application/xml",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "sitemap",
         "root": false,
         "ugly": true,
         "weight": 0
      },
      "sitemapindex": {
         "baseName": "sitemap",
         "isHTML": false,
         "isPlainText": false,
         "mediaType": "application/xml",
         "noUgly": false,
         "notAlternative": false,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "sitemap",
         "root": true,
         "ugly": true,
         "weight": 0
      },
      "webappmanifest": {
         "baseName": "manifest",
         "isHTML": false,
         "isPlainText": true,
         "mediaType": "application/manifest+json",
         "noUgly": false,
         "notAlternative": true,
         "path": "",
         "permalinkable": false,
         "protocol": "",
         "rel": "manifest",
         "root": false,
         "ugly": false,
         "weight": 0
      }
   }
}
baseName
(string) 发布文件的基本名称。默认值是 index。
isHTML
(bool) 是否将输出格式分类为 HTML。此值确定何时注入 LiveReload 脚本，并且与 permalinkable 结合，决定是否生成 别名重定向。默认值是 false。
isPlainText
(bool) 是否使用 Go 的 text/template 包而不是 html/template 包为此输出格式解析模板。默认值是 false。
mediaType
(string) 发布文件的 媒体类型。这必须匹配一个 配置的媒体类型。
notAlternative
(bool) 是否从 Page 对象上的 AlternativeOutputFormats 方法返回的值中排除此输出格式。默认值是 false。
noUgly
(bool) 当站点配置中启用了 uglyURLs 时，是否禁用此输出格式的 ugly URLs。默认值是 false。
path
(string) 此输出格式发布路径的第一个段。此路径段相对于 publishDir 的根目录。如果省略，Hugo 将使用文件的原始内容路径进行发布。
permalinkable
(bool) 在调用 Page 对象上的 Permalink 和 RelPermalink 方法时，是否返回渲染输出格式而不是主输出格式的 URL。与 isHTML 一起，这必须为 true 才能创建 别名重定向。html 和 amp 输出格式默认启用。默认值是 false。
protocol
(string) 此输出格式 URL 的协议（方案）。例如，https:// 或 webcal://。默认值是站点配置中 baseURL 参数的方案，通常是 https://。
rel
(string) 输出格式与当前页面的关系。Hugo 使用此属性确定当前页面的 规范输出格式。对于预定义的 html 输出格式，默认值是 canonical；对于所有其他预定义的输出格式，默认值是 alternate。
root
(bool) 是否将文件发布到发布目录的根目录。默认值是 false。
ugly
(bool) 当站点配置中 uglyURLs 为 false 时，是否为此输出格式启用 uglyURLs。默认值是 false。
weight
(int) 当设置为非零值时，Hugo 使用 weight 作为排序输出格式的首要条件，回退到输出格式的名称。较轻的项目浮到顶部，而较重的项目沉到底部。Hugo 根据排序顺序依次渲染输出格式。默认值是 0，但 html 输出格式除外，其默认权重为 10。

修改输出格式

您可以修改任何默认输出格式。例如，当同时生成 json 和 html 渲染时，要优先 json 渲染，调整 weight：

outputFormats:
  html:
    weight: 2
  json:
    weight: 1

[outputFormats]
  [outputFormats.html]
    weight = 2
  [outputFormats.json]
    weight = 1

{
   "outputFormats": {
      "html": {
         "weight": 2
      },
      "json": {
         "weight": 1
      }
   }
}

上面的示例表明，当您修改默认内容格式时，您只需要定义与默认值不同的属性。

创建输出格式

您可以根据需要创建新的输出格式。例如，您可能希望创建输出格式以支持 Atom 源。

步骤 1
输出格式需要指定媒体类型。因为 Atom 源使用 application/atom+xml，这不是 默认媒体类型 之一，所以您必须先创建它。 
mediaTypes:
  application/atom+xml:
    suffixes:
    - atom

[mediaTypes]
  [mediaTypes.'application/atom+xml']
    suffixes = ['atom']

{
   "mediaTypes": {
      "application/atom+xml": {
         "suffixes": [
            "atom"
         ]
      }
   }
}

详见 配置媒体类型 获取更多信息。

步骤 2
创建新的输出格式： 
outputFormats:
  atom:
    mediaType: application/atom+xml
    noUgly: true

[outputFormats]
  [outputFormats.atom]
    mediaType = 'application/atom+xml'
    noUgly = true

{
   "outputFormats": {
      "atom": {
         "mediaType": "application/atom+xml",
         "noUgly": true
      }
   }
}

请注意，我们对所有其他输出格式属性使用默认设置。

步骤 3
指定要渲染此输出格式的页面 类型： 
outputs:
  home:
  - html
  - rss
  - atom
  section:
  - html
  - rss
  - atom
  taxonomy:
  - html
  - rss
  - atom
  term:
  - html
  - rss
  - atom

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

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

详见 配置输出 获取更多信息。

步骤 4
创建模板来渲染输出格式。由于 Atom 源是列表，您需要创建列表模板。查阅 模板查找顺序 找到正确的模板路径： 
layouts/list.atom.atom

我们将编写模板代码作为练习留给您。目标结果类似于 嵌入式 RSS 模板。

列出输出格式

要访问输出格式，每个 Page 对象提供两种方法：OutputFormats（用于所有格式，包括当前格式）和 AlternativeOutputFormats。使用 AlternativeOutputFormats 在站点的 head 元素中创建链接 rel 列表，如下所示：

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

链接到输出格式

默认情况下，Page 对象的 Permalink 和 RelPermalink 方法返回 主输出格式 的 URL，通常是 html。无论使用什么模板，此行为都保持一致。

例如，在 page.json.json 中，您将看到：

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

要使这些方法返回 当前 模板输出格式的 URL，您必须为该格式设置 permalinkable 设置为 true。

在相同的 page.json.json 模板中为 json 设置 permalinkable 为 true：

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

模板查找顺序

每个输出格式都需要符合 模板查找顺序 的模板。

为了在模板查找顺序中获得最高的特异性，在文件名中包含页面类型、输出格式和后缀：

[页面类型].[输出格式].[后缀]

例如，对于栏目页面：

输出格式 模板路径
html layouts/section.html.html
json layouts/section.json.json
rss layouts/section.rss.xml
Last updated: January 1, 0001
Improve this page