Link render hooks

Markdown

Markdown 連結有三個組成部分：連結文字、連結目標，以及可選的連結標題。

[Post 1](/posts/post-1 "My first post")
 ------  -------------  -------------
  文字     目標             標題

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

上下文

連結渲染 Hook 模板接收以下上下文：

Destination

（string）連結目標。

Page

（page）對當前頁面的引用。

PageInner

（page）通過 RenderShortcodes 方法嵌套的頁面引用。查看詳細資訊。

PlainText

（string）連結描述的純文字。

Text

（template.HTML）連結描述。

Title

（string）連結標題。

範例

在預設配置中，Hugo 根據 CommonMark 規範 渲染 Markdown 連結。要創建與預設相同的渲染 Hook：

<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}

若要為外部連結添加 rel="external" 屬性：

{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
  {{- if $u.IsAbs }} rel="external"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}

預設

Hugo 包含一個 內建的連結渲染 Hook，用於解析 Markdown 連結目標。此功能預設為停用，可在網站配置中啟用：

markup:
  goldmark:
    renderHooks:
      link:
        enableDefault: true

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

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

即使主題或模組提供了自訂渲染 Hook，也會覆蓋上述內建渲染 Hook。

內建的連結渲染 Hook 會通過尋找匹配的頁面來解析內部 Markdown 目標，接著回退到匹配的 頁面資源，再回退到匹配的 全域資源。對於遠端目標，會直接傳遞，且當無法解析目標時，渲染 Hook 不會拋出錯誤或警告。

全域資源必須放置在 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"
         }
      ]
   }
}

PageInner 詳細資訊

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

{{ with site.GetPage (.Get 0) }}
  {{ .RenderShortcodes }}
{{ end }}

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

{{% include "/posts/p2" %}}

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

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

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

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

• 內嵌連結渲染掛載
• 內嵌圖片渲染掛載