Passthrough 渲染钩子

概述

Hugo 使用 Goldmark 将 Markdown 渲染为 HTML。Goldmark 支持自定义扩展来扩展其核心功能。Goldmark 的 passthrough 扩展 捕获并保留分隔文本片段内的原始 Markdown，包括分隔符本身。这些被称为 passthrough 元素。

根据您选择的定界符，Hugo 将 passthrough 元素分类为 块 或 内联 。考虑这个人为编造的例子：

这是一个

\[block\]

带有开始和结束块定界符的 passthrough 元素。

这是一个 \(inline\) 带有开始和结束内联定界符的 passthrough 元素。

更新您的站点配置以启用 passthrough 扩展并为每种 passthrough 元素类型（ 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 中使用任何一个。

Goldmark passthrough 扩展通常与 MathJax 或 KaTeX 显示引擎一起使用，以渲染用 LaTeX 或 Tex 编写的 数学表达式 。

要启用 passthrough 元素的自定义渲染，请创建一个渲染钩子。

上下文

Passthrough 渲染钩子模板接收以下 [上下文]：

属性

(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 为 块 passthrough 元素填充 Attributes 映射。Markdown 属性不适用于 内联 元素。

内部内容

(string) passthrough 元素的内部内容，不包括定界符。

序号

(int) 页面上 passthrough 元素的基于零的序号。

页面

(page) 对当前页面的引用。

页面内部内容

(page) 对通过 RenderShortcodes 方法嵌套的页面的引用。 查看详情 。

位置

(string) passthrough 元素在页面内容中的位置。

类型

(string) passthrough 元素类型， block 或 inline 。

示例

作为使用 MathJax 或 KaTeX 显示引擎渲染数学表达式的替代方法，创建一个 passthrough 渲染钩子，该钩子调用 transform.ToMath 函数：

{{ if eq .Type "block" }}
  {{ $opts := dict "displayMode" true }}
  {{ transform.ToMath .Inner $opts }}
{{ else }}
  {{ transform.ToMath .Inner }}
{{ end }}

尽管您可以像上面那样使用一个带有条件逻辑的模板，但您也可以为每种 Type 的 passthrough 元素创建单独的模板：

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

PageInner 详情

PageInner 的主要用例是解析相对于已包含的 Page 的链接和 页面资源 。例如，创建一个“include”短代码，从多个内容文件组合一个页面，同时保留脚注和目录的全局上下文：

{{ with .Get 0 }}
  {{ with $.Page.GetPage . }}
    {{- .RenderShortcodes }}
  {{ else }}
    {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
{{ end }}

然后在你的Markdown中调用短代码：

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

在渲染 /posts/p2 期间触发的任何渲染钩子将获得：

• 调用 Page 时为 /posts/p1
• 调用 PageInner 时为 /posts/p2

如果与 PageInner 不相关，则 PageInner 回退到 Page 的值，并始终返回值。

作为一个实际示例，Hugo的嵌入式链接和图像渲染钩子使用 PageInner 方法来解析Markdown链接和图像目标。查看每个源代码：

• 嵌入式链接渲染钩子
• 嵌入式图像渲染钩子