圖片渲染鉤子

Markdown

Markdown 圖片有三個組成部分：圖片描述、圖片目標和可選的圖片標題。

![white kitten](/images/kitten.jpg "A kitten!")
  ------------  ------------------  ---------
  description      destination        title

這些組件會傳遞到渲染鉤子 上下文 中，如下所示。

上下文

圖片_渲染鉤子_ 模板接收以下上下文：

Attributes

(map) Markdown 屬性，如果您的站點配置如下則可用：

markup:
  goldmark:
    parser:
      attribute:
        block: true
      wrapStandAloneImageWithinParagraph: false

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      wrapStandAloneImageWithinParagraph = false
      [markup.goldmark.parser.attribute]
        block = true

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            },
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

Destination

(string) 圖片目標。

IsBlock

(bool) 報告獨立圖片是否未包裹在段落元素中。

Ordinal

(int) 頁面上圖片的從零開始的序號。

Page

(page) 對當前頁面的引用。

PageInner

(page) 對通過 RenderShortcodes 方法嵌套的頁面的引用。詳見。

PlainText

(string) 圖片描述（純文本形式）。

Text

(template.HTML) 圖片描述。

Title

(string) 圖片標題。

示例

在默認配置中，Hugo 根據 CommonMark 規范 渲染 Markdown 圖片。要創建執行相同操作的渲染鉤子：

<img src="{{ .Destination | safeURL }}"
  {{- with .PlainText }} alt="{{ . }}"{{ end -}}
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- /* 刪除尾隨換行符 */ -}}

要在 figure 元素中渲染獨立圖片：

{{- if .IsBlock -}}
  <figure>
    <img src="{{ .Destination | safeURL }}"
      {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    >
    {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
  </figure>
{{- else -}}
  <img src="{{ .Destination | safeURL }}"
    {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    {{- with .Title }} title="{{ . }}"{{ end -}}
  >
{{- end -}}

請注意，上述需要以下站點配置：

markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      wrapStandAloneImageWithinParagraph = false

{
   "markup": {
      "goldmark": {
         "parser": {
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

嵌入式

Hugo 包含一個 嵌入式圖片渲染鉤子 來解析 Markdown 圖片目標。您可以在站點配置中調整其行為。這是默認設置：

markup:
  goldmark:
    renderHooks:
      image:
        useEmbedded: auto

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        useEmbedded = 'auto'

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "image": {
               "useEmbedded": "auto"
            }
         }
      }
   }
}

如上所示設置為 auto 時，Hugo 會自動為多語言單主機站點使用嵌入式圖片渲染鉤子，特別是在 共享頁面資源復制 功能被禁用時。這是此類站點的默認行為。如果您的項目、模塊或主題定義了自定義圖片渲染鉤子，則會使用這些鉤子。

您還可以配置 Hugo always（始終）使用嵌入式圖片渲染鉤子、僅作為 fallback（後備）使用，或 never（從不）使用。請參閱 詳情。

嵌入式圖片渲染鉤子通過查找匹配的 頁面資源 來解析內部 Markdown 目標，如果找不到則回退到匹配的 全局資源。遠程目標會直接傳遞，如果無法解析目標，渲染鉤子不會拋出錯誤或警告。

您必須將全局資源放在 assets 目錄中。如果您已將資源放在 static 目錄中，並且無法或不願移動它們，則必須通過在站點配置中包含以下兩個條目，將 static 目錄掛載到 assets 目錄：

module:
  mounts:
  - source: assets
    target: assets
  - source: static
    target: assets

[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    source = 'static'
    target = 'assets'

{
   "module": {
      "mounts": [
         {
            "source": "assets",
            "target": "assets"
         },
         {
            "source": "static",
            "target": "assets"
         }
      ]
   }
}

請注意，嵌入式圖片渲染鉤子不執行圖片處理。其唯一目的是解析 Markdown 圖片目標。

PageInner 詳情

PageInner 的主要用途是相對於包含的 Page 解析鏈接和 頁面資源。例如，創建一個 “include” 短代碼，從多個內容文件組合頁面，同時保留腳注和目錄的全局上下文：

{{ with .Get 0 }}
  {{ with $.Page.GetPage . }}
    {{- .RenderShortcodes }}
  {{ else }}
    {{ errorf "短代碼 %q 無法找到 %q。參見 %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "短代碼 %q 需要一個位置參數來指示要包含的文件的邏輯路徑。參見 %s" .Name .Position }}
{{ end }}

然後在您的 Markdown 中調用短代碼：

{{% include "/posts/post-2" %}}

在渲染 /posts/post-2 時觸發的任何渲染鉤子將獲得：

• 調用 Page 時獲得 /posts/post-1
• 調用 PageInner 時獲得 /posts/post-2

如果不相關，PageInner 會回退到 Page 的值，並且始終返回一個值。

作為實際示例，Hugo 的嵌入式鏈接和圖像渲染鉤子使用 PageInner 方法來解析 Markdown 鏈接和圖像目標。請參閱各自的源代碼：

• 嵌入式鏈接渲染鉤子
• 嵌入式圖像渲染鉤子