HUGO

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 入门指南
    • 本节内容
    • 快速开始
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 配置构建
    • 术语表
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • 前言
    • 构建选项
    • 页面资源
    • 图像处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基础模板
    • 主页模板
    • 单页模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 嵌入式模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • cast
    • collections
    • compare
    • crypto
    • css
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hash
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Menu entry
    • Page
    • Pager
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • 图像
    • 链接
    • 直通
    • 表格
  • 短代码
    • 本节内容
    • 评论
    • 详细信息
    • 图
    • Gist
    • 高亮
    • Instagram
    • Param
    • QR
    • Ref
    • Relref
    • Vimeo
    • X
    • YouTube
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 转译为 CSS
    • PostCSS
    • 后处理
    • JavaScript 构建
    • 资源压缩
    • 连接资源
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • CLI
  • 故障排除
    • 本节内容
    • 审计
    • 日志
    • 检查
    • 弃用
    • 性能
    • 常见问题
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • 搜索
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Azure 静态 Web 应用上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitHub Pages 上托管
    • 在 GitLab Pages 上托管
    • 在 KeyCDN 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
模板 基础

自定义输出格式

Hugo 可以输出多种格式的内容,包括日历事件、电子书格式、Google AMP 和 JSON 搜索索引,或任何自定义文本格式。

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

媒体类型

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

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

类型 后缀
application/json [json]
application/manifest+json [webmanifest]
application/octet-stream [webmanifest]
application/pdf [pdf]
application/rss+xml [xml rss]
application/toml [toml]
application/wasm [wasm]
application/xml [xml]
application/yaml [yaml yml]
font/otf [otf]
font/ttf [ttf]
image/bmp [bmp]
image/gif [gif]
image/jpeg [jpg jpeg jpe jif jfif]
image/png [png]
image/svg+xml [svg]
image/tiff [tif tiff]
image/webp [webp]
text/asciidoc [adoc asciidoc ad]
text/calendar [ics]
text/css [css]
text/csv [csv]
text/html [html htm]
text/javascript [js jsm mjs]
text/jsx [jsx]
text/markdown [md mdown markdown]
text/org [org]
text/pandoc [pandoc pdc]
text/plain [txt]
text/rst [rst]
text/tsx [tsx]
text/typescript [ts]
text/x-sass [sass]
text/x-scss [scss]
video/3gpp [3gpp 3gp]
video/mp4 [mp4]
video/mpeg [mpg mpeg]
video/ogg [ogv]
video/webm [webm]
video/x-msvideo [avi]

注意

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

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

hugo。
     
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

hugo。
     
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 内置输出格式的完整集合

类型 baseName isHTML isPlainText mediaType noUgly path permalinkable protocol rel
amp index true false text/html false amp true amphtml
calendar index false true text/calendar false false webcal:// alternate
css styles false true text/css false false stylesheet
csv index false true text/csv false false alternate
html index true false text/html false true canonical
json index false true application/json false false alternate
markdown index false true text/markdown false false alternate
robots robots false true text/plain false false alternate
rss index false false application/rss+xml true false alternate
sitemap sitemap false false application/xml false false sitemap
webappmanifest manifest false true application/manifest+json false false manifest
  • 一个页面可以输出为任意数量的输出格式,并且您可以定义无限数量的输出格式,只要它们在文件系统上解析为唯一的路径即可。在上面的表格中,最好的例子是 amp 与 html。amp 的 path 值为 amp,因此它不会覆盖 html 版本;例如,我们现在可以同时拥有 /index.html 和 /amp/index.html。
  • mediaType 必须与定义的媒体类型匹配。
  • 您可以定义新的输出格式或重新定义内置的输出格式;例如,如果您想将 amp 页面放在不同的路径中。

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

hugo。
     
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 属性,默认输出格式是基于该属性设置的。

hugo。
     
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 列表来更改此设置。

来自站点配置文件的示例

hugo。
     
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 的输出格式

content/example.md
     
---
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" . }}

在此页面上

  • 媒体类型
  • 输出格式定义
  • 页面的输出格式
  • 列出输出格式
  • 链接到输出格式
  • 输出格式的模板
上次更新时间:2024 年 6 月 25 日:重组模板部分 (748bf065f)
改进此页面
由 Hugo 作者
Hugo Logo
  • 提交问题
  • 获取帮助
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo 赞助商

您的公司?
 

Hugo 徽标的版权为 © Steve Francia 2013–2025。

Hugo Gopher 基于 Renée French 的原创作品。

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 入门指南
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • 短代码
  • Hugo 模块
  • Hugo 管道
  • CLI
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护