自訂輸出格式

這一頁說明如何正確配置您的網站的媒體類型與輸出格式，並且在哪裡創建自訂輸出格式的模板。

媒體類型

媒體類型（以前稱為 MIME 類型）是互聯網上文件格式和格式內容的兩部分識別符。

以下是 Hugo 內建的所有媒體類型：

注意：

• 可以新增自訂媒體類型或更改預設值；例如，若您想將 text/html 的後綴更改為 asp。
• 後綴 是用於 Hugo 中 URL 和檔案名稱的媒體類型值。
• 類型 是定義新的自訂 輸出格式（見下文）時必須使用的識別符。
• 完整的媒體類型集會註冊到 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 媒體類型的後綴更改為 asp。

注意： 這些媒體類型是為 您的輸出格式 配置的。如果您想重新定義 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"
      }
   }
}

輸出格式定義

給定一個媒體類型及其他配置，您將獲得一個 輸出格式。

以下是 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 的網站，它會產生一個純文字的首頁，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，即使在網站配置中 uglyURLs 為 true。預設為 false。

path

(string) 發佈檔案所在的目錄路徑，這是相對於發佈目錄的根目錄的路徑。

permalinkable

(bool) 若為 true，則 Page 物件上的 Permalink 和 RelPermalink 方法返回該輸出格式，而非主輸出格式（詳見下文）。預設為 false，但對於 html 和 amp 輸出格式預設為 true。

protocol

(string) 該輸出格式 URL 的協議（方案）。例如，https:// 或 webcal://。預設為網站配置中 baseURL 參數的方案，通常為 https://。

rel

(string) 若提供，您可以將此值分配給 <link> 元素中的 rel 屬性，在模板中迭代輸出格式時使用。預設為 alternate。

root

(bool) 若為 true，檔案將被發佈到發佈目錄的根目錄。預設為 false。

ugly

(bool) 若為 true，則啟用 uglyURLs，即使在網站配置中 uglyURLs 為 false。預設為 false。

weight

(int) 當設為非零值時，Hugo 會將 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）必須與已定義的輸出格式名稱匹配，並且可以在前端資料中覆蓋。

以下是內容檔案中的前端資料範例，定義了渲染 Page 的輸出格式：

---
outputs:
- html
- amp
- json
title: 範例
---

+++
outputs = ['html', 'amp', 'json']
title = '範例'
+++

{
   "outputs": [
      "html",
      "amp",
      "json"
   ],
   "title": "範例"
}

列出輸出格式

每個 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" . }}