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