HUGO
Menu
GitHub 87548 stars Mastodon

直通元素渲染鉤子

創建直通元素渲染鉤子模板以覆蓋 Goldmark 直通擴展捕獲的文本片段的渲染。
New in v0.132.0

概述

Hugo 使用 Goldmark 將 Markdown 渲染為 HTML。Goldmark 支持自定義擴展來擴展其核心功能。直通 擴展捕獲並保留原始 Markdown 在 delimited 文本片段中，包括分隔符本身。這些被稱為 直通元素。

根據您選擇的分隔符，Hugo 會將直通元素分類為 塊級 或 內聯。考慮這個人為的例子：

content/example.md 
這是一個

\[塊級\]

直通元素，帶有開始和結束塊級分隔符。

這是一個 \(內聯\) 直通元素，帶有開始和結束內聯分隔符。

更新您的站點配置以啟用直通擴展並為每種直通元素類型定義開始和結束分隔符，block 或 inline。例如：

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 中使用其中任意一組。

直通擴展通常與 MathJax 或 KaTeX 顯示引擎結合使用，以渲染用 LaTeX 標記語言編寫的 數學表達式。

要啟用直通元素的自定義渲染，請創建直通元素渲染鉤子。

上下文

直通元素_渲染鉤子_ 模板接收以下 上下文：

Attributes
(map) Markdown 屬性，如果您的站點配置如下則可用： 
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 進行客戶端 JavaScript 渲染數學標記，不如創建一個調用 transform.ToMath 函數的直通元素渲染鉤子。

layouts/_markup/render-passthrough.html 
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
  {{- with .Err }}
    {{- errorf "無法使用 transform.ToMath 函數將數學標記渲染為 HTML。KaTeX 顯示引擎拋出以下錯誤：%s：參見 %s。" . $.Position }}
  {{- else }}
    {{- .Value }}
    {{- $.Page.Store.Set "hasMath" true }}
  {{- end }}
{{- end -}}

然後，在您的基礎模板中，在 head 元素內有條件地包含 KaTeX CSS：

layouts/baseof.html 
<head>
  {{ $noop := .WordCount }}
  {{ if .Page.Store.Get "hasMath" }}
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
      integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
      crossorigin="anonymous"
    >
  {{ end }}
</head>

在上面，請注意使用 noop 語句來強制在 Store.Get 方法檢查 hasMath 值之前進行內容渲染。

雖然您可以使用一個帶有條件邏輯的模板（如上所示），但您也可以為每種 Type 的直通元素創建單獨的模板：

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

PageInner 詳情

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

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

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

content/posts/post-1.md 
{{% include "/posts/post-2" %}}

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

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

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

PageInner 方法僅與調用 RenderShortcodes 方法的短代碼相關，並且您必須使用 Markdown 表示法 調用短代碼。

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

Last updated: January 1, 0001
Improve this page