RENDER HOOKS

Passthrough render hooks

New in v0.132.0

概述

Hugo 使用 Goldmark 將 Markdown 渲染為 HTML。Goldmark 支援自訂擴展以擴充其核心功能。Goldmark 的 傳遞擴展 會捕捉並保留被定界符包圍的原始 Markdown，包括定界符本身。這些被稱為傳遞元素。

根據您選擇的定界符，Hugo 將傳遞元素分類為區塊或內嵌。以下是一個範例：

content/sample.md
This is a

\[block\]

passthrough element with opening and closing block delimiters.

This is an \(inline\) passthrough element with opening and closing inline delimiters.

更新您的網站配置以啟用傳遞擴展，並為每種類型（block 或 inline）的傳遞元素定義開頭和結尾的定界符。例如：

hugo.
      
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
        enable: true

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)']]

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "\\[",
                        "\\]"
                     ],
                     [
                        "$$",
                        "$$"
                     ]
                  ],
                  "inline": [
                     [
                        "\\(",
                        "\\)"
                     ]
                  ]
               },
               "enable": true
            }
         }
      }
   }
}

在上述範例中，有兩組 block 的定界符。您可以在 Markdown 中使用任意一組。

Goldmark 傳遞擴展通常與 MathJax 或 KaTeX 顯示引擎結合使用，用於渲染以 LaTeX 或 Tex 撰寫的 數學表達式。

若要啟用傳遞元素的自訂渲染，請建立渲染 Hook。

上下文

傳遞渲染 Hook 模板會接收以下 上下文：

Attributes

（map）Markdown 屬性，若您按以下配置網站則可用：

hugo.
      
markup:
  goldmark:
    parser:
      attribute:
        block: true

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

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            }
         }
      }
   }
}

Hugo 會為區塊傳遞元素填充 Attributes 映射。Markdown 屬性不適用於內嵌元素。

Inner

（string）傳遞元素的內部內容，不包括定界符。

Ordinal

（int）傳遞元素在頁面上的零基序號。

Page

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

PageInner

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

Position

（string）傳遞元素在頁面內容中的位置。

Type

（string）傳遞元素的類型，為 block 或 inline。

範例

除了使用 MathJax 或 KaTeX 顯示引擎渲染數學表達式外，您也可以建立一個傳遞渲染 Hook，調用 transform.ToMath 函數：

layouts/_default/_markup/render-passthrough.html
{{ if eq .Type "block" }}
  {{ $opts := dict "displayMode" true }}
  {{ transform.ToMath .Inner $opts }}
{{ else }}
  {{ transform.ToMath .Inner }}
{{ end }}

雖然可以像上述範例那樣使用一個帶有條件邏輯的模板，但您也可以為每種傳遞元素的 Type 創建單獨的模板：

layouts/
└── _default/
    └── _markup/
        ├── render-passthrough-block.html
        └── render-passthrough-inline.html

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 中連結和圖片的目標位置。請參考以下來源程式碼：

Section templates Page resources