代码块渲染钩子

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 语法高亮器来渲染代码示例。您可以通过指定一个或多个 高亮选项 来控制渲染代码的外观。

上下文

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

Attributes

(map) 来自信息字符串的通用属性。

Inner

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

Options

(map) 来自信息字符串的高亮选项。如果 Type 是空字符串或 Chroma 语法高亮器不支持的代码语言，则此映射为空。但是，在这种情况下，高亮选项可在 Attributes 映射中使用。

Ordinal

(int) 页面上代码块的从零开始的序号。

Page

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

PageInner

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

Position

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

Type

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

示例

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

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

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

layouts/
  └── _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 }}

然后在您的基础模板的 底部（在闭合 body 标签之前）包含此代码片段：

{{ 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 "短代码 %q 无法找到 %q。参见 %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "短代码 %q 需要一个位置参数来指示要包含的文件的逻辑路径。参见 %s" .Name .Position }}
{{ end }}

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

{{% include "/posts/post-2" %}}

在渲染 /posts/post-2 时触发的任何渲染钩子将获得：

• 调用 Page 时获得 /posts/post-1
• 调用 PageInner 时获得 /posts/post-2

如果不相关，PageInner 会回退到 Page 的值，并且始终返回一个值。

作为实际示例，Hugo 的嵌入式链接和图像渲染钩子使用 PageInner 方法来解析 Markdown 链接和图像目标。请参阅各自的源代码：

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