transform.HighlightCodeBlock
返回代码块渲染钩子上下文中收到的、已高亮的代码。
transform.HighlightCodeBlock 函数使用 alecthomas/chroma 包,为代码块渲染钩子(render hook)上下文中收到的代码生成带语法高亮的 HTML。该函数只在代码块渲染钩子内有意义。
这一页解决什么问题
你写了一个代码块渲染钩子(layouts/_markup/render-codeblock.html),想完全接管代码块的 HTML:加标题栏、加复制按钮、改外层结构。这时代码和语言名由 Hugo 以上下文的形式交给你,transform.HighlightCodeBlock 负责把它高亮——它只在代码块渲染钩子里有意义,在普通模板里调用没有可用的上下文。
它的返回值不是字符串,而是一个 HighlightResult 对象,取内容要用两个方法之一:.Wrapped(带 <div><pre><code> 包裹)或 .Inner(只有高亮后的片段,外层自己写)。
什么时候用,什么时候别用
该用:
- 自定义代码块渲染钩子,需要自己控制外层结构;
- 想在默认高亮结果上改选项(用
merge .Options (dict …)保留作者在围栏属性里写的选项); - 想在语言不被支持时退回纯文本(配合
transform.CanHighlight)。
别用:
- 普通模板里高亮一段字符串 → 用
transform.Highlight;HighlightCodeBlock需要渲染钩子上下文; - 只想要默认高亮输出 → 什么都不用做,Hugo 默认就会高亮围栏代码块;
- 想渲染 Markdown 字符串 → 用
transform.Markdownify。
参数
返回值
transform.HighlightCodeBlock 返回一个 HighlightResult 对象,它有两个方法。
Wrapped- (
template.HTML)返回用<div>、<pre>、<code>元素包裹的高亮代码。它与transform.Highlight函数返回的值完全相同。 Inner- (
template.HTML)返回不带任何包裹元素的高亮代码,便于你自行包裹。
示例
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}要覆盖默认选项:
{{ $opts := merge .Options (dict "lineNos" true) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}当高亮器不支持该语言时退回纯文本:
{{ $opts := dict }}
{{ if not (transform.CanHighlight .Type) }}
{{ $opts = dict "type" "text" }}
{{ end }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}选项
transform.HighlightCodeBlock 函数接受一个选项映射。
anchorLineNos- (
bool)是否把每个行号渲染为 HTML 锚点元素,即把外层span元素的id属性设为行号。lineNos为false时无意义。默认false。 codeFences- (
bool)是否高亮围栏代码块。默认true。 guessSyntax- (
bool)当LANG参数留空,或设为一个没有对应词法分析器(lexer)的语言时,是否自动识别语言。无法自动识别语言时回退为纯文本词法分析器。默认false。 hl_Lines- (
string)要高亮代码中需要强调的行,以空格分隔。要强调第 2、3、4、7 行,把该值设为2-4 7。该选项与lineNoStart选项相互独立。 hl_inline- (
bool)是否渲染不带外层容器的高亮代码。默认false。 lineAnchors- (
string)把行号渲染为 HTML 锚点元素时,将该值加在外层span元素的id属性之前。当一个页面包含两个或更多代码块时,这样可以得到唯一的id属性。lineNos或anchorLineNos为false时无意义。 lineNoStart- (
int)第一行开头显示的行号。lineNos为false时无意义。默认1。 lineNos- (
any)控制行号的显示方式。默认false。true:启用行号,具体形式由lineNumbersInTable决定。false:关闭行号。inline:启用行内行号(把lineNumbersInTable设为false)。table:启用表格形式的行号(把lineNumbersInTable设为true)。
lineNumbersInTable- (
bool)是否把高亮代码渲染为含两个单元格的 HTML 表格:左单元格放行号,右单元格放代码。lineNos为false时无意义。默认true。 noClasses- (
bool)是否使用内联 CSS 样式,而不使用外部 CSS 文件。默认true。要使用外部 CSS 文件,请把该值设为false,并用hugo gen chromastyles命令生成 CSS 文件:shhugo gen chromastyles --style=github > assets/css/highlight.css(0.164.0 新增)
有些配色方案分别提供浅色与深色两套调色板。用
--mode参数为指定模式生成样式表,用--modeSelector参数把每个选择器收拢到顶层模式类之下(例如.dark .chroma):shhugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css在根元素上添加或移除
dark类即可切换深色模式。省略--mode时,Hugo 按配色方案自身的默认模式生成样式表。也可以在模板中使用
css.ChromaStyles函数生成样式表。 style- (
string)应用到高亮代码上的 CSS 样式。该值大小写不敏感。默认monokai。参见语法高亮配色方案。 tabWidth- (
int)把高亮代码中的每个制表符替换为这么多个空格。noClasses为false时无意义。默认4。 wrapperClass- (0.140.2 新增)
- (
string)高亮代码最外层元素使用的类或类名列表。默认highlight。 code- (0.162.0 新增)
- (
string)覆盖从代码块上下文收到的代码。 type- (0.162.0 新增)
- (
string)覆盖从代码块上下文收到的语言。
完整示例:在渲染钩子里取 .Wrapped 与 .Inner
在 layouts/_markup/render-codeblock.html 里这样写(示例同时输出两者,便于对照):
{{ $opts := merge .Options (dict "lineNos" false) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
<!--WRAPPED-->{{ $result.Wrapped }}<!--INNER-->{{ $result.Inner }}内容文件里放一个围栏代码块:
```python
x = 1
```Hugo 渲染出(HTML 中)的实际结果为(Wrapped 与 Inner 以注释标记分隔):
<!--WRAPPED--><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-python" data-lang="python"><span style="display:flex;"><span>x <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span></span></span></code></pre></div><!--INNER--><span style="display:flex;"><span>x <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span></span></span>你应当看到什么:.Wrapped 自带 <div class="highlight"><pre><code …> 三层包裹;.Inner 只有高亮后的 <span> 片段——所以「自己写外层」时用 .Inner,其余情况用 .Wrapped。merge .Options (dict "lineNos" false) 保留了作者在围栏属性里写的选项。
语言不被支持时:实测同一个钩子处理 ```klingon 代码块,.Wrapped 得到 <pre tabindex="0"><code class="language-klingon" data-lang="klingon">nuqneH</code></pre>,.Inner 只有 nuqneH(没有高亮、也没有 highlight 包裹)。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows,默认高亮配置,代码块渲染钩子中调用。
| 情况 | .Wrapped |
.Inner |
是否报错 |
|---|---|---|---|
语言受支持(python) |
<div class="highlight"><pre …><code class="language-python" …>…</code></pre></div> |
只有高亮后的 <span> 片段 |
否 |
语言不受支持(klingon) |
<pre tabindex="0"><code class="language-klingon" …>nuqneH</code></pre> |
nuqneH(纯文本) |
否 |
传 merge .Options (dict "lineNos" false) |
选项生效,输出与默认一致(默认本就无行号) | 同上 | 否 |
| 在非渲染钩子处调用 | —— | —— | 上游未说明;本函数的用途就是渲染钩子,别处没有代码块上下文 |
| 返回类型 | highlight.HighlightResult(实测字段为方法 .Wrapped、.Inner,均为 template.HTML) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 构建失败/输出为空 | 在普通局部模板里调用没有效果 | 该函数只在代码块渲染钩子内有上下文 | 把逻辑放进 layouts/_markup/render-codeblock.html |
| 没报错但结果不对 | 自定义外层时出现「套了两层」 | 用了 .Wrapped(已含 <div><pre><code>) |
自定义包裹时改用 .Inner |
| 没报错但结果不对 | 钩子里丢掉作者写的围栏属性 | 没有把 .Options 合并进自己的选项 |
用 merge .Options (dict …),自己的选项写在后面以覆盖 |
| 没报错但结果不对 | 不支持的语言没有高亮也没有提示 | 高亮器静默退回纯文本(实测) | 用 transform.CanHighlight 判断后自行加提示或改 type |
更多排查入口见故障排查。