RENDER HOOKS

Image render hooks

Markdown

一個 Markdown 圖片包含三個組成部分：圖片描述、圖片目的地，以及可選的圖片標題。

![白色小貓](/images/kitten.jpg "一隻小貓！")
  ------------  ------------------  ---------
    描述             目的地            標題

這些組成部分會作為渲染 Hook 的 上下文 傳遞，如下所示。

上下文

圖片渲染 Hook 模板接收到以下上下文：

Attributes

(map) Markdown 屬性，如果您的網站配置如下，則會提供這些屬性：

hugo.
      
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) 如果獨立圖片未包裹在段落元素中，則返回 true。

Ordinal

(int) 頁面中圖片的零基索引。

Page

(page) 當前頁面的參考。

PageInner
New in v0.125.0

(page) 通過 RenderShortcodes 方法嵌套的頁面參考。查看詳情。

PlainText

(string) 圖片描述的純文字版本。

Text

(template.HTML) 圖片描述的 HTML。

Title

(string) 圖片標題。

範例

在預設配置下，Hugo 根據 CommonMark 規範 渲染 Markdown 圖片。以下是創建具備相同行為的渲染 Hook 範例：

layouts/_default/_markup/render-image.html
<img src="{{ .Destination | safeURL }}"
  {{- with .Text }} alt="{{ . }}"{{ end -}}
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- /* 消除尾部換行符 */ -}}

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

layouts/_default/_markup/render-image.html
{{- if .IsBlock -}}
  <figure>
    <img src="{{ .Destination | safeURL }}"
      {{- with .Text }} alt="{{ . }}"{{ end -}}
    >
    {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
  </figure>
{{- else -}}
  <img src="{{ .Destination | safeURL }}"
    {{- with .Text }} alt="{{ . }}"{{ end -}}
    {{- with .Title }} title="{{ . }}"{{ end -}}
  >
{{- end -}}

請注意，上述範例需要以下網站配置：

hugo.
      
markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false

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

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

預設行為

New in v0.123.0

Hugo 包含一個 內嵌圖片渲染 Hook，用於解析 Markdown 圖片的目的地。該功能預設為關閉，您可以在網站配置中啟用它：

hugo.
      
markup:
  goldmark:
    renderHooks:
      image:
        enableDefault: true

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = true

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "image": {
               "enableDefault": true
            }
         }
      }
   }
}

即使主題或模組提供自定義渲染 Hook，也會覆蓋上述內嵌渲染 Hook，無論配置如何。

內嵌圖片渲染 Hook 透過搜尋匹配的 頁面資源 或後備到匹配的 全域資源 來解析內部 Markdown 圖片的目的地。遠端目的地會直接通過，且即使無法解析目的地，渲染 Hook 也不會拋出錯誤或警告。

您必須將全域資源放置於 assets 目錄中。如果您已將資源放置於 static 目錄中，並且無法或不願將其移動，則必須透過在網站配置中包含以下條目，將 static 目錄掛載到 assets 目錄：

hugo.
      
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"
         }
      ]
   }
}

請注意，內嵌圖片渲染 Hook 不進行圖片處理。其唯一目的是解析 Markdown 圖片的目的地。

PageInner 詳細資訊

New in v0.125.0

PageInner 的主要用途是解析相對於包含的 Page 的連結和 頁面資源。例如，建立一個「include」掛載程式碼，從多個內容檔案組合成一個頁面，同時保留註腳和目錄的全域上下文：

layouts/shortcodes/include.html
{{ with site.GetPage (.Get 0) }}
  {{ .RenderShortcodes }}
{{ end }}

然後在您的 Markdown 中呼叫此掛載程式碼：

content/posts/p1.md
{{% include "/posts/p2" %}}

在渲染 /posts/p2 時觸發的任何渲染掛載將獲得：

  • /posts/p1 當呼叫 Page
  • /posts/p2 當呼叫 PageInner

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

作為一個實際範例，Hugo 的內嵌連結和圖片渲染掛載使用 PageInner 方法解析 Markdown 中連結和圖片的目標位置。請參考以下來源程式碼：

js.Build Home templates