代码高亮与增强

本页讲解代码块相关配置：高亮引擎与主题（prismjs/highlightjs）、代码块交互增强（收缩/折行/展开/复制/全屏）、语言标签、复制版权。全部在主题配置的 code 段内。

主题配置以 userConfig/_config.tmp.yml 为权威源（CI 时覆盖主题配置）。注意：Markdown 渲染器层面的 prismjs 服务端渲染由根 _config.yml 的 prismjs 插件负责，本节讲的是主题层的代码块展示配置。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

1. 高亮引擎（highlight）

用途：选择代码高亮实现库，控制行号与明暗两套主题。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：文章内 ``` 代码块按所选库着色，左侧出现行号，暗色模式下自动换用暗色主题。

对应配置（主题配置，code.highlight 段）：

code:
  highlight:
    enable: true          # 总开关
    line_number: true     # 是否显示行号
    lib: "prismjs"        # 高亮库：highlightjs | prismjs

1.2 常用选项

① 关掉行号

效果：代码块左侧不再显示 1、2、3…，代码区更宽。

对应配置：

code:
  highlight:
    line_number: false

② 切换引擎

效果：改用 highlight.js 着色，主题名与语法覆盖面随之改变（见 §3）。

对应配置：

code:
  highlight:
    lib: "highlightjs"

③ 整体关闭高亮

效果：代码块变成纯文本，不再着色与加行号。

对应配置：

code:
  highlight:
    enable: false

1.3 全部可调项

1.4 边界与冲突

• lib 决定使用哪套引擎，并激活下方对应子配置——prismjs 读 code.highlight.prismjs，highlightjs 读 code.highlight.highlightjs；两套同时存在但只有一套生效。
• 本博客使用 prismjs。
• 引擎层高亮与根 _config.yml 的 prismjs 插件是两条通道，改主题配置不会改变服务端渲染行为。

1.5 小结

• 最小可用：enable: true + lib
• 嫌行号挤：line_number: false
• 换库：改 lib，记得配套改 §2 或 §3 的 style

2. prismjs 主题与渲染模式

用途：亮色/暗色两套高亮主题（跟随明暗模式切换），以及高亮生成方式。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：亮色模式下代码块用 default 配色，切到暗色模式自动变成 tomorrow night 配色；treeview/autolinker/diffhighlight 三个增强插件生效。

对应配置（主题配置，code.highlight.prismjs 段）：

code:
  highlight:
    prismjs:
      style: "default"            # 亮色主题：prismjs.com 右侧圆形按钮挑样式，或填 CSS 链接
      style_dark: "tomorrow night" # 暗色主题
      preprocess: false           # true 本地静态生成；false 浏览器 JS 生成
      treeview: true              # 代码块显示 treeview（tree -F 树形）
      autolinker: true            # 代码块中的链接可点击
      diffhighlight: true         # 代码差异高亮（+/- 行）

2.2 常用选项

① 换亮色主题

效果：代码块配色换成所选主题（背景、关键字、字符串颜色全变）。

对应配置：

code:
  highlight:
    prismjs:
      style: "tomorrow"

② 换暗色主题

效果：暗色模式下代码块用新配色。

对应配置：

code:
  highlight:
    prismjs:
      style_dark: "dark"

③ 切到构建时静态渲染

效果：高亮 HTML 在构建时生成，页面无 JS 也能看到着色（但 treeview/autolinker/diffhighlight 不可用）。

对应配置：

code:
  highlight:
    prismjs:
      preprocess: true

④ 关掉差异高亮

效果：+/- 行不再有绿/红底色。

对应配置：

code:
  highlight:
    prismjs:
      diffhighlight: false

两种渲染模式对比（preprocess）：

2.3 全部可调项

2.4 边界与冲突

• 切主题在 prismjs.com 挑样式名填入（如 "tomorrow night"），也可直接填 CSS 链接。
• style_dark 在暗色模式下自动生效，无需手动切换。
• preprocess: true 与 treeview/autolinker/diffhighlight 冲突：静态生成只支持部分插件，三者会失效。

2.5 小结

• 最小可用：style + style_dark
• 要增强插件：保持 preprocess: false
• 要 SEO/无 JS：preprocess: true，接受增强失效
• 暗色看不清：先调 style_dark

3. highlightjs 主题（备用引擎）

用途：若切换 lib: "highlightjs"，使用以下配置。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：代码块改用 highlight.js 着色，亮色用 github gist、暗色用 dark。

对应配置（主题配置，code.highlight.highlightjs 段）：

code:
  highlight:
    highlightjs:
      style: "github gist"   # 亮色主题（highlightjs.org/static/demo 挑）
      style_dark: "dark"     # 暗色主题

必须同时把 code.highlight.lib 设为 "highlightjs"，否则此段不生效。

3.2 常用选项

① 换亮色主题

效果：代码块亮色配色变化。

对应配置：

code:
  highlight:
    highlightjs:
      style: "atom-one-light"

② 换暗色主题

效果：暗色模式下配色变化。

对应配置：

code:
  highlight:
    highlightjs:
      style_dark: "atom-one-dark"

3.3 全部可调项

3.4 边界与冲突

• 此段只在 lib: "highlightjs" 时生效；用 prismjs 时改了也没反应。
• highlight.js 没有 treeview/autolinker/diffhighlight 对应项。

3.5 小结

• 要切换：先改 lib，再填两个 style
• 主题名哪来：highlightjs.org 的 demo 页
• 用 prismjs 就别碰这段

4. 代码块增强（code 段）

用途：代码块的展示与交互行为：折叠、折行、展开全部、全屏、复制按钮、语言标签。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

效果：代码块右上角出现复制按钮与全屏按钮；超高代码块默认收起并显示「展开全部」；左上角显示语言标签（未标注时显示 TEXT）；长行横向滚动而不折行。

对应配置（主题配置，code 段）：

code:
  shrink: true            # 代码块是否可以收缩（折叠）
  break: false            # 代码是否折行（false 则长行横向滚动）
  show_full: true         # 代码是否全部显示
  height_limit: "450px"   # show_full 高度阈值：超过此高度显示"展开全部"按钮
  show_expand: true       # 代码框是否全屏显示
  copy_btn: true          # 复制代码按钮
  language:
    enable: true          # 代码块语言标签
    default: "TEXT"       # 未标注语言时的默认标签

4.2 常用选项

① 长行折行

效果：超长代码行自动换行，不再横向滚动（会破坏对齐）。

对应配置：

code:
  break: true

② 调整「展开全部」阈值

效果：阈值越小，越多代码块被收起。

对应配置：

code:
  height_limit: "300px"

③ 关闭复制按钮

效果：代码块不再显示复制图标。

对应配置：

code:
  copy_btn: false

④ 改语言标签默认值

效果：未写语言名的代码块显示新标签。

对应配置：

code:
  language:
    default: "代码"

效果说明（逐项）：

• show_full: true + height_limit：超高代码块默认收起，点击"展开全部"查看，避免长代码撑爆页面
• break: false：长行横向滚动而非折行，保持代码格式
• copy_btn: true：悬停显示复制按钮，一键复制代码
• code.language.default：没写语言名的代码块显示 TEXT 标签（可改成 "代码" 等）

4.3 全部可调项

4.4 边界与冲突

• height_limit 必须是带单位的字符串（"450px"），纯数字会被忽略。
• show_full: false 时 height_limit 无意义，长代码直接全展开。
• break: true 与行号同时开启时，折行后的续行没有行号，阅读体验会变差。

4.5 小结

• 最小可用：保持默认即可
• 长代码撑页：show_full + 合适的 height_limit
• 移动端横向滚动烦：break: true
• 标签想中文化：language.default

5. 复制版权（code.copyright）

用途：复制文章内容（含代码）超过一定字符数时，自动在剪贴板追加版权声明。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：读者复制超过 120 个字符的正文/代码后，粘贴内容末尾自动多出一行「本文章著作权归作者所有，任何形式的转载都请注明出处。」

对应配置（主题配置，code.copyright 段）：

code:
  copyright:
    enable: true
    minCharNumber: 120    # 至少复制多少个字符就追加版权信息
    description: 本文章著作权归作者所有，任何形式的转载都请注明出处。

5.2 常用选项

① 调触发阈值

效果：minCharNumber: 300 时短复制不追加，只有长段复制才带声明。

对应配置：

code:
  copyright:
    minCharNumber: 300

② 改声明文字

效果：粘贴出来的版权文案变化。

对应配置：

code:
  copyright:
    description: 转载请注明出处并保留原文链接。

③ 关闭复制版权

效果：复制内容不再追加任何文字。

对应配置：

code:
  copyright:
    enable: false

5.3 全部可调项

5.4 边界与冲突

• 这是复制行为的版权保护（区别于文章底部版权卡片 post.copyright）：读者复制正文/代码后，粘贴内容末尾自动带上来源声明。
• 阈值按字符数计，代码块整体复制通常远超 120。
• 与 post.copyright 互不影响，可各自开关。

5.5 小结

• 最小可用：enable: true
• 嫌烦：把 minCharNumber 调大
• 文案要改：只改 description
• 和文章版权卡片是两件事

附：代码高亮速查表