代码块渲染钩子

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) 对当前页面的引用。

页面内部内容

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

位置

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

类型

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

示例

在其默认配置中，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/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 不相关，则 PageInner 回退到 Page 的值，并始终返回值。

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

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