语法高亮
Hugo 基于 Chroma 的代码块高亮、常用配置项与自定义样式表;含配置位置、构建验证方法与转义陷阱。
开始之前,你需要
- 会写围栏代码块,知道项目配置
hugo.toml在哪。 - 有一个能查看产物 HTML 或页面源码的环境,改完能立刻比对。
读完之后你能
- 在围栏代码块上使用行号、强调行与配色等选项,并知道默认值写在哪里;
- 把高亮从内联样式切换成 class + 自建样式表,并生成对应的 CSS;
- 正确转义短代码示例,避免整站构建失败;
- 解释「代码块没有颜色」「行号不显示」这两类现象。
这一页解决什么问题
Hugo 用 Chroma 完成语法高亮(syntax highlighting),提供三条途径:在模板中调用 transform.Highlight 函数、在任何内容格式中使用 highlight 短代码(shortcode),以及在 Markdown 内容格式中使用围栏代码块(code fence)。日常写作以第三种为主。
高亮本身不需要配置就能用;会踩坑的是它的两个「开关」和一条「铁律」:
- 配置写在哪——所有高亮默认值都在项目配置的
[markup.highlight]区段里,围栏选项与配置键同名; noClasses决定样式的来源——默认true时 Hugo 把颜色内联进 HTML,开箱即用;改成false后只输出 class,站点必须自己提供 CSS,否则代码块会变成一片没有颜色的文本;- 短代码示例必须转义——Hugo 在 Markdown 解析之前就提取短代码,未转义的示例会让整个站点构建失败(见转义短代码定界符)。
验证高亮是否生效:在任意页面写一个围栏代码块,构建后查看产物 HTML。
hugo你应当看到什么:产物 HTML 里代码被包在 <div class="highlight"> 之类的最外层元素里(类名由 wrapperClass 决定,默认 highlight),代码的每个记号带 <span> 与颜色或 class。如果产物里只有 <pre><code>、没有任何 span,说明这块代码没有走 Chroma——通常是语言标识缺失或不受支持(默认按纯文本输出,见 LANG 的说明)。
用 hugo config 可以确认高亮的最终生效配置:
hugo config | findstr /C:"highlight" # Windows
hugo config | grep -A20 highlight # macOS / Linux实测(Hugo 0.167,本站):本站 hugo.toml 里设的是 markup.highlight.noClasses = false(即使用 class 而非内联样式),主题自带 assets/css/syntax.css 提供对应的配色样式表,并被打包进产物(产物里能看到 css/syntax.min.<哈希>.css)。也就是说,本页生成样式表一节描述的正是本站已经在用的模式——本站不需要再额外生成 CSS;你自己新建站点并改成 class 模式时,才需要补这一步。
三种高亮方式
Hugo 用 Chroma 完成语法高亮(syntax highlighting),提供三条途径:在模板中调用 transform.Highlight 函数、在任何内容格式中使用 highlight 短代码(shortcode),以及在 Markdown 内容格式中使用围栏代码块(code fence)。日常写作以第三种为主。
highlight 短代码内部调用的正是这个函数,它根据传入的代码、语言与选项生成高亮后的 HTML。
Markdown 内容格式下,围栏代码块默认就会高亮,因此 highlight 短代码很少用到,它主要用来给行内代码片段着色。
围栏代码块
默认配置下,Hugo 会高亮如下形式的代码块:
```LANG [OPTIONS]
CODE
```CODE:要高亮的代码。LANG:语言标识,取自支持的语言,大小写不敏感。省略或不受支持时按纯文本输出,不做高亮——与 CommonMark 规范一致,只有已知的语言标识才会触发语义层面的高亮。OPTIONS:零个或多个键值对,用空格或逗号分隔并包在花括号中,键名大小写不敏感;默认值写在项目配置里。
例如:
```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)
}
}
```你应当看到什么:行号 3(import "fmt")与 6–8 行会带上强调样式,行号显示在代码左侧(linenos=inline),配色是 emacs。选项值有两种写法:hl_lines 在项目配置里是空格分隔的字符串(hl_Lines = "2-4 7"),在围栏里既可以写 [3,"6-8"] 数组,也可以写 "3 6-8" 字符串,两者等价。
本站实际渲染效果
下面这一块是同一段围栏在本站真的渲染出来的样子(三项选项一起写)——写法在上、产物就在眼前,不是把产物再贴一遍:
1package main
2
3import "fmt"
4
5func main() {
6 for i := 0; i < 3; i++ {
7 fmt.Println("Value of i:", i)
8 }
9}对照上面的「你应当看到什么」:行号确实在代码左侧(linenos=inline),第 3 行与第 6–8 行确实带上了强调底色(hl_lines)——这两项在本站是一眼可见的。
但「配色是 emacs」这一句在本站看不出差别,这是本站配置决定的,值得单独说清楚:hugo.toml 里设了 [markup.highlight] noClasses = false,即输出 Chroma 的类名而不是内联样式,颜色统一由 assets/css/syntax.css 决定。此时 style=… 选项只影响内联样式,因此换任何风格名都不会改变这一块的颜色。要让 style 生效,有两条路:把 noClasses 改成 true(回到内联样式),或者用 hugo gen chromastyles 生成目标风格的样式表替换现有配色——后者才是本站这类「类名输出」站点该走的路。
配置项
高亮行为由配置文件的 [markup.highlight] 区段控制,键名即围栏选项名,可参考配置 Hugo:
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
anchorLineNos |
布尔 | false |
行号是否渲染为锚点元素,即把所在 span 的 id 设为行号;lineNos 为 false 时无意义 |
codeFences |
布尔 | true |
是否高亮围栏代码块 |
guessSyntax |
布尔 | false |
语言标识留空或对应词法分析器(lexer)不存在时是否自动识别语言,识别失败则回退为纯文本 |
hl_Lines |
字符串 | 空 | 需要强调的行号,空格分隔,例如 2-4 7 表示强调第 2、3、4、7 行,与 lineNoStart 无关 |
hl_inline |
布尔 | false |
是否渲染不带外层容器的行内高亮代码 |
lineAnchors |
字符串 | 空 | 行号作锚点时附加在 id 前的前缀,用于同一页面存在多个代码块时区分;lineNos 或 anchorLineNos 为 false 时无意义 |
lineNoStart |
整数 | 1 |
第一行显示的行号 |
lineNos |
任意 | false |
行号显示方式:true 按 lineNumbersInTable 决定,false 关闭,inline 行内显示,table 表格列显示 |
lineNumbersInTable |
布尔 | true |
是否用两列表格渲染,左列行号、右列代码 |
noClasses |
布尔 | true |
true 输出内联样式,false 输出 class 并需自行提供样式表 |
style |
字符串 | monokai |
配色方案名称,大小写不敏感 |
tabWidth |
整数 | 4 |
每个制表符替换为多少个空格;noClasses 为 false 时无意义 |
wrapperClass |
字符串 | highlight |
最外层元素使用的类名 |
注意 guessSyntax 的适用范围:Chroma 收录约 300 种语言的词法分析器,其中只有 5 种实现了自动语言识别。
生成样式表
把 noClasses 设为 false 后,Hugo 不再内联样式,而是为每个记号输出 class,站点必须自己提供 CSS,否则代码块会失去配色。样式表可用内置命令生成:
hugo gen chromastyles --style=github > assets/css/highlight.css部分配色方案同时提供浅色与深色两套调色板,可以用 --mode 指定其中之一,并用 --modeSelector 把选择器统一收在顶层模式类(例如 .dark .chroma)之下:
hugo 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 时按方案自身的默认模式生成。也可以在模板中改用 css.ChromaStyles 函数生成样式表。生成的 CSS 既可以作为普通样式表引入,也可以交给资源管道(asset pipeline)与主样式表一起打包。
转义短代码定界符
在正文中书写短代码示例时,必须用 Hugo 的转义写法,否则短代码会在 Markdown 解析之前被提取,直接导致构建失败。转义的做法是把注释标记 /* 与 */ 插进定界符之间:
```text {linenos=inline}
{{</* shortcode-1 */>}}
{{%/* shortcode-2 */%}}
```上例渲染出的正是形如 {{< shortcode-1 >}} 与 {{% shortcode-2 %}} 的转义文本——它们展示的是短代码的长相,而不会在构建时真的执行。注意这段示例本身就写在围栏代码块里,而其中的嵌套转义仍然被解析:围栏代码块并不豁免短代码提取,正文里凡是出现短代码写法的地方(包括行内代码与围栏代码块中的示例)都必须转义。highlight 短代码的调用形式是 {{< highlight go "linenos=inline, hl_lines=3 6-8, style=emacs" >}} … {{< /highlight >}},参数与围栏选项一一对应,用法见短代码。
支持的语言
语言标识用于 transform.Highlight 函数、highlight 短代码与围栏代码块,写标识而不是语言名称:
go、bash、toml、yaml、json、html、css、md、text等常用标识;- 完整清单由 Chroma 提供,可用
hugo gen chromastyles --help或 Chroma 官方仓库查询当前版本收录的语言与别名。
什么时候用哪种高亮方式
| 情形 | 该用 | 理由 |
|---|---|---|
| Markdown 正文里的代码示例(绝大多数情况) | 围栏代码块 | 零配置,写作时就地生效 |
| 行内的一句代码需要着色 | highlight 短代码 |
围栏代码块只能整块用;短代码可以嵌在句子中间 |
| 高亮结果来自变量、数据或循环 | transform.Highlight 函数 |
只有函数能处理运行时才知道的代码文本 |
| 站点需要跟随主题切换深浅配色 | noClasses = false + 自建样式表 |
样式表可以按模式切换,内联样式做不到 |
别用:noClasses = false 却不引入样式表 |
—— | 代码块会失去全部配色,看起来像高亮坏了,实际是少了 CSS |
| 别用:把语言标识留空又指望有颜色 | —— | 与 CommonMark 一致,只有已知语言标识才触发高亮;留空按纯文本输出 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 构建失败 | failed to extract shortcode: template for shortcode "…" not found,且报错位置像在别处 |
正文里写了未转义的短代码示例;Hugo 在 Markdown 之前提取短代码,找不到模板就中止整站构建 | 把示例改写成 {{< name >}} 形式;要展示转义写法本身时用 {{</* name */>}},见转义短代码定界符 |
| 没报错但结果不对 | 代码块完全没有颜色 | 语言标识缺失或拼错(按纯文本输出);或 noClasses = false 而没有引入生成的样式表 |
补上正确标识;生成并引入 CSS,见生成样式表 |
| 没报错但结果不对 | 设了 lineNos 却看不到行号 |
行号需要代码块本身有内容行;lineNos = true 还受 lineNumbersInTable 影响(默认用两列表格渲染) |
显式写 lineNos = "inline" 或 "table";用产物 HTML 确认 <table> 是否生成 |
| 没报错但结果不对 | 同一页多个代码块的行号锚点互相冲突 | 没有给 lineAnchors 设前缀,id 重复 |
设 lineAnchors 与 anchorLineNos = true,让每个块的锚点带独立前缀 |
| 没报错但结果不对 | 制表符缩进的代码对齐错乱 | tabWidth 与编辑器制表符宽度不一致 |
调整 tabWidth(默认 4),或统一用空格缩进 |
| 没报错但结果不对 | 改了 style 但配色没变 |
实际生效的是 [markup.highlight] 里的值,内容里的围栏选项没写;或 noClasses = false 时配色由样式表决定,与 style 无关 |
用 hugo config 核对;改 class 模式后要重新生成样式表 |
更多排查入口见故障排查。