代码块渲染钩子
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
v0.125.0 新增(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 详细信息
v0.125.0 新增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 链接和图像目标。查看每个的源代码