highlight
用 highlight 短代码插入带语法高亮的代码片段:LANG 与 OPTIONS 两个位置参数、全部选项、可复制示例与实测输出。
开始之前,你需要
- 站点能构建成功(
hugo --renderToMemory退出码为 0)。 - 知道围栏代码块的写法(三个反引号 + 语言名),本页大半内容都在与它对照。
读完之后你能
- 说清什么时候该用围栏代码块、什么时候才需要
highlight短代码; - 写出带选项的
highlight调用(行号、强调行、内联高亮),并知道参数必须用位置参数; - 在
public/里核对高亮的产物结构(div.highlight/code.language-*),判断语言是否真的生效。
这一页解决什么问题
Hugo 默认就会高亮围栏代码块,所以这一页要回答的不是「怎么让代码有颜色」,而是三类围栏代码块解决不了的需求:
- 给行内代码加高亮——反引号包起来的
code默认没有高亮,highlight短代码可以; - 让选项跟着数据走——短代码是模板,选项可以由模板参数拼出来(围栏代码块的信息字符串是静态文本);
- 在自定义短代码里复用高亮——调用
transform.Highlight函数,或在模板中包装highlight。
highlight 短代码调用 transform.Highlight 函数,根据传入的代码、语言与选项生成带语法高亮的 HTML。
参数
highlight 短代码接受三个参数,其中两个必须写成位置参数(这一点上游文档没有明说,见下面的实测说明)。
{{< highlight LANG OPTIONS >}}
CODE
{{< /highlight >}}CODE- (
string)要高亮的代码。写成开闭标记之间的内部内容,不作为参数传入。 LANG- (
string)代码的语言。取值大小写不敏感。作为第一个位置参数传入。 OPTIONS- (
string)零个或多个用空格分隔、包在引号中的键值对。作为第二个位置参数传入。可以为每个选项在项目配置中设置默认值,键名大小写不敏感。
示例
{{< highlight go "linenos=inline, hl_lines=3 6-8, style=emacs" >}}
package main
import "fmt"
func main() {
for i := 0; i < 3; i++ {
fmt.Println("Value of i:", i)
}
}
{{< /highlight >}}Hugo 据此渲染出高亮后的 HTML:LANG 决定使用哪个词法分析器(lexer),OPTIONS 决定行号、强调行与配色等外观。
你应当看到什么:产物里这一段变成 <div class="highlight">,里面是 <pre><code class="language-go" data-lang="go">,代码被切成大量 <span style="…">;linenos=inline 让每一行前面多出行号,hl_lines=3 6-8 让这些行带上背景色。
也可以把 highlight 短代码用于行内代码片段:
This is some {{< highlight go "hl_inline=true" >}}fmt.Println("inline"){{< /highlight >}} code.这一行渲染成:
<p>This is some <code class="code-inline language-go">…</code> code.</p>注意 hl_inline=true 换来的不是 <div class="highlight">,而是一个行内 <code class="code-inline language-…">——这正是它能嵌在句子中间的原因。
考虑到上例写法冗长,如果需要频繁高亮行内代码片段,可以用更短的名字和预设选项创建自己的短代码:
{{ $code := .Inner | strings.TrimSpace }}
{{ $lang := or (.Get 0) "go" }}
{{ $opts := dict "hl_inline" true "noClasses" true }}
{{ transform.Highlight $code $lang $opts }}This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code.本站实际渲染效果
下面两段是真的用 highlight 短代码渲染出来的,可以直接和上文「你应当看到什么」的描述对照:
1package main
2
3import "fmt"
4
5func main() {
6 fmt.Println("hello")
7}同一个短代码加上 hl_inline=true,就变成能嵌在句子中间的行内高亮:
This is some fmt.Println("inline") code.
对照点:上面是 <div class="highlight"> 包着的块级代码,下面是 <code class="code-inline language-go">,只多了一个词法分析器的类名。配色与本站围栏代码块完全一致——markup.highlight.noClasses = false,样式来自 assets/css/syntax.css。
选项
短代码的 OPTIONS 参数与围栏代码块的选项一一对应:anchorLineNos、codeFences、guessSyntax、hl_Lines、hl_inline、lineAnchors、lineNoStart、lineNos、lineNumbersInTable、noClasses、style、tabWidth、wrapperClass。各选项的含义、类型与默认值见语法高亮,那里同时给出了生成外部样式表的 hugo gen chromastyles 命令。
几个最常用的:
| 选项 | 作用 | 例 |
|---|---|---|
linenos |
显示行号(inline 或 table) |
"linenos=inline" |
hl_lines |
强调指定行 | "hl_lines=3 6-8" |
hl_inline |
输出行内高亮 <code>,而不是块级 <div> |
"hl_inline=true" |
style |
配色方案名 | "style=emacs" |
noClasses |
是否直接写内联样式(false 表示用 CSS 类,需要自己提供样式表) |
"noClasses=false" |
lineNoStart |
起始行号 | "lineNoStart=10" |
实测(Hugo 0.167):
OPTIONS是一个字符串参数,多个键值对写在同一个引号里用空格或逗号分隔;写成两个独立参数不会生效。- 语言名写错(例如
nosuchlang)不报错:输出<pre><code class="language-nosuchlang" data-lang="nosuchlang">,内容原样、没有颜色。排查「高亮没生效」时先看class里的语言名是不是你想要的。 - 配合行内模式时,开闭标记之间不能为空——空内容会渲染出一个空的
<code class="code-inline …">。
什么时候用,什么时候别用
该用:
- 行内代码要高亮(围栏代码块做不到);
- 需要同一段高亮逻辑放进自定义短代码或模板里复用;
- 选项需要由数据决定,例如按页面参数切换配色。
别用:
-
普通的块级代码 → 直接用围栏代码块,写起来短得多,选项完全一样:
需求 围栏代码块(信息字符串) highlight短代码显示行号 linenos=inlineLANG+OPTIONS两个位置参数强调某几行 hl_lines=[3,"6-8"]"hl_lines=3 6-8"展示文件名 file="main.go"不支持,要在外层自己写 行内高亮 不支持 "hl_inline=true" -
代码内容来自文件 → 用
os.ReadFile一类函数在模板里读取,不必把整段代码抄进正文; -
只是想让代码里的语法被高亮成静态图或截图 → 与 Hugo 无关。
验证方法
-
在内容里写一个最小调用:
content/example.mdmd{{< highlight go "linenos=inline" >}} fmt.Println("hello") {{< /highlight >}} -
构建并查看产物:
bashhugo -
打开
public/example/index.html,搜索highlight。
你应当看到什么:出现 <div class="highlight">…<code class="language-go" data-lang="go">…;行号来自 linenos=inline,应当能看到数字 1。
- 只看到
<pre tabindex="0"><code>fmt.Println("hello")</code></pre>(没有language-go)→ 语言没传进去,通常是写成了lang=命名参数; - 看到
language-nosuchlang→ 语言名拼错,Hugo 不报错; - 看到
language-go但整段没有颜色 → 检查站点是否关掉了高亮,或noClasses与样式表是否对得上。
常见坑
| 类别 | 现象 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 代码没有颜色 | LANG 写成了命名参数 lang="go",被当成未识别参数丢弃 |
改成位置参数:{{< highlight go "…" >}} |
| 没报错但结果不对 | 选项没生效 | OPTIONS 写成了多个参数,或没放进同一个引号 |
选项合并为一个字符串,放在语言名之后 |
| 没报错但结果不对 | 行内高亮输出为空 | 开闭标记之间没有内容 | 把要高亮的代码写在中间 |
| 没报错但结果不对 | 颜色变了或整段没样式 | style 指定的配色与站点样式表不一致;或 noClasses=false 却没有引入 Chroma 样式表 |
见语法高亮与 hugo gen chromastyles |
| 没报错但结果不对 | 页面上直接显示了短代码的调用原文 | 把文档里的转义写法抄进了正文 | 删掉 /* 与 */ |
| 报错看不懂 | failed to extract shortcode: template for shortcode "highlight" not found |
layouts/_shortcodes/ 下有同名文件但内容有误,或名字拼错 |
删掉自定义文件即恢复内置版本 |
| 报错看不懂 | unrecognized character in shortcode action: U+0028 '(' 之类 |
在短代码参数里写了 printf 一类的函数调用——短代码参数只接受字面量 |
先用模板拼好值,或把选项直接写死在调用里 |
更多排查入口见故障排查。