HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
TEMPLATES FUNDAMENTALS

自定义输出格式

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

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

媒体类型

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

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

Type suffixes
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 。
  • Suffixes 是 Hugo 中将用于该媒体类型的 URL 和文件名。
  • Type 是定义新的/自定义 输出格式(见下文)时必须使用的标识符。
  • 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 内置输出格式的完整集合:

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

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

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

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

{{ partial "mytextpartial.csv" . }}

On this page

  • 媒体类型
  • 输出格式定义
  • 页面的输出格式
  • 列出输出格式
  • 链接到输出格式
  • 输出格式的模板
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护