鏈接渲染鉤子

Markdown

Markdown 鏈接有三個組成部分：鏈接文本、鏈接目標和可選的鏈接標題。

[Post 1](/posts/post-1 "My first post")
 ------  -------------  -------------
  text    destination       title

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

上下文

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

Destination

(string) 鏈接目標。

Page

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

PageInner

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

PlainText

(string) 鏈接描述（純文本形式）。

Text

(template.HTML) 鏈接描述。

Title

(string) 鏈接標題。

示例

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

<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* 刪除尾隨換行符 */ -}}

要為外部鏈接添加設置為 external 的 rel 屬性：

{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
  {{- if $u.IsAbs }} rel="external"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* 刪除尾隨換行符 */ -}}

嵌入式

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

markup:
  goldmark:
    renderHooks:
      link:
        useEmbedded: auto

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

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "link": {
               "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"
         }
      ]
   }
}

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 鏈接和圖像目標。請參閱各自的源代碼：

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