Chroma 是什么

Chroma 是 Hugo 内置的代码语法高亮引擎，基于 Go 语言编写，是 Pygments 的纯 Go 替代品。它支持超过 200 种编程语言的语法解析和数十种配色主题，无需安装 Python 或额外依赖即可使用。

相较于前端方案（如 Prism.js、Highlight.js），Chroma 在构建阶段完成高亮转换，输出纯静态 HTML + CSS，不增加客户端 JavaScript 负担，页面加载速度更快。

基础配置

在 hugo.toml 的 [markup.highlight] 段配置：

1[markup.highlight]
2  codeFences = true           # 启用围栏代码块 ```lang
3  guessSyntax = true          # 自动检测未标注语言的代码块
4  lineNos = true              # 显示行号
5  lineNumbersInTable = false  # false=行内样式, true=表格样式
6  noClasses = false           # false=使用外部CSS, true=内联样式
7  style = "monokai"           # 高亮主题
8  tabWidth = 2                # Tab 宽度

关键参数说明

关于 lineNumbersInTable

设为 false（行内模式）时，行号和代码在同一 <span> 内，适合复制粘贴；设为 true（表格模式）时，行号和代码分列显示，复制不会带行号，但需要额外 CSS 处理。

常用配色主题

Hugo 内置了大量 pygments-style 主题，在 style 字段切换即可：

在本地可以运行 hugo gen chromastyles --style=monokai > syntax.css 导出任意主题的完整 CSS 文件，按需修改后放入 assets/css/ 覆盖默认样式。

明暗双主题适配

如果博客同时支持明亮和暗黑模式，推荐使用 noClasses = false + 外部 CSS 方案：

1. 在 [markup.highlight] 中设置 style = "monokai"（暗色主题作为基础）
2. 在浅色模式下，通过 CSS 覆盖 chroma 类的背景色和文字色
3. 或使用 Hugo 的 hugo gen chromastyles 同时导出两份 CSS，根据 [data-theme] 切换

也可以使用 CSS 变量策略，将 chroma 生成的静态颜色替换为 CSS 变量，实现一套代码适配双主题。

代码块增强

除了语法高亮本身，本站的代码块还集成了三项增强：

• 复制按钮：代码块右上角的复制图标，点击一键复制全部代码
• 折叠/展开：超长代码块（超过一定行数）自动折叠，点击展开查看完整代码
• 暗黑适配：深色背景 + 适配暗色模式的文字色，切换主题时无缝过渡

这些增强通过独立的 JavaScript 模块实现，与 Chroma 引擎解耦，可单独开启或关闭。

常见问题

Q: 为什么复制代码时带了行号？

A: 将 lineNumbersInTable 设为 false（行内模式），或者设为 true（表格模式）配合 CSS 让行号列不可选中。

Q: 如何添加新的语言支持？

A: Chroma 内置了 200+ 语言，Hugo 会自动识别。如果需要特殊语言，确保代码块正确标注语言标识符即可。

Q: 如何禁用高亮？

A: 使用不存在的语言标识符，如 ```text 或 ```plain，Chroma 会跳过该代码块。