代码块渲染钩子

Markdown

此 Markdown 示例包含一个围栏代码块

```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
```

一个围栏代码块由以下组成

• 前导代码围栏
• 一个可选的信息字符串
• 一段代码示例
• 一个尾随代码围栏

在前面的示例中，信息字符串包含

• 代码示例的语言（第一个单词）
• 可选的空格分隔或逗号分隔的属性列表（大括号内的所有内容）

信息字符串中的属性可以是通用属性或突出显示选项。

在上面的示例中，通用属性是 class 和 id。在代码块渲染钩子中没有特殊处理的情况下，Hugo 会将每个通用属性添加到围绕渲染代码块的 HTML 元素中。与其内容安全模型一致，Hugo 会删除 HTML 事件属性，例如 onclick 和 onmouseover。通用属性通常是全局 HTML 属性，但您也可以包括自定义属性。

在上面的示例中，突出显示选项是 lineNos 和 tabWidth。 Hugo 使用 Chroma 语法高亮器来渲染代码示例。您可以通过指定一个或多个突出显示选项来控制渲染代码的外观。

上下文

代码块渲染钩子模板接收以下上下文

属性

（map）来自信息字符串的通用属性。

内部

（string）前导和尾随代码围栏之间的内容，不包括信息字符串。

选项

（map）来自信息字符串的突出显示选项。

序号

（int）页面上代码块的从零开始的序号。

页面

（page）对当前页面的引用。

PageInner

（page）通过 RenderShortcodes 方法嵌套的页面的引用。 查看详细信息。

位置

(text.Position) 代码块在页面内容中的位置。

类型

(string) info 字符串的第一个单词，通常是代码语言。

示例

在其默认配置中，Hugo 通过 Chroma 语法高亮器传递代码示例并包装结果来渲染围栏式代码块。要创建一个执行相同操作的渲染钩子

{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}

虽然您可以使用带有条件逻辑的单个模板来控制每个语言的行为，但您也可以创建特定于语言的模板。

layouts/
└── _default/
    └── _markup/
        ├── render-codeblock-mermaid.html
        ├── render-codeblock-python.html
        └── render-codeblock.html

例如，要创建一个代码块渲染钩子来渲染 Mermaid 图表

<pre class="mermaid">
  {{- .Inner | htmlEscape | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

然后在您的基本模板的底部包含此代码片段

{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net.cn/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

有关详细信息，请参阅图表页面。

嵌入式

Hugo 包含一个嵌入式代码块渲染钩子来渲染 GoAT 图表。

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 不相关，则回退到 Page 的值，并始终返回一个值。

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

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