语法高亮 | Hexo

Hexo 对 highlight.js 与 prismjs 两种代码高亮库提供内建支持。本篇教程将展示如何将 Hexo 的内建语法高亮组件整合至你的模板中。

如何在文章中插入代码块

{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

{% code [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcode %}

```[language] [title] [url] [link text] [additional options]
code snippet
```

上面的第三种是 Markdown 的 fenced code block 语法。 Hexo 对其进行了扩展，使其支持更多特性。在标签插件文档中你可以找到可用的选项。

提示：Hexo 支持用任何格式书写文章，只需安装相应渲染插件即可。可以使用 markdown、ejs、swig、nunjucks、pug、asciidoc 等。无论使用哪种格式，这三种代码块语法始终可用。

配置

v7.0.0以下：

# _config.yml
highlight:
  enable: true
  auto_detect: false
  line_number: true
  line_threshold: 0
  tab_replace: ""
  exclude_languages:
    - example
  wrap: true
  hljs: false
prismjs:
  enable: false
  preprocess: true
  line_number: true
  line_threshold: 0
  tab_replace: ""

v7.0.0及以上：

# _config.yml
syntax_highlighter: highlight.js
highlight:
  auto_detect: false
  line_number: true
  line_threshold: 0
  tab_replace: ""
  exclude_languages:
    - example
  wrap: true
  hljs: false
prismjs:
  preprocess: true
  line_number: true
  line_threshold: 0
  tab_replace: ""

以上为 Hexo 的默认配置。

禁用

v7.0.0及以下：

# _config.yml
highlight:
  enable: false
prismjs:
  enable: false

v7.0.0及以上：

# _config.yml
syntax_highlighter: # empty

当 highlight.enable 和 prismjs.enable 均为 false （v7.0.0以下）或 syntax_highlighter 为空（v7.0.0及以上）时，代码块输出的 HTML 由相应的渲染器控制。举个例子：marked.js（Hexo 的默认 Markdown 渲染器 hexo-renderer-marked 由此驱动）会把语言加入 <code> 标签的 class 中：

```yaml
hello: hexo
```

<pre>
  <code class="yaml">hello: hexo</code>
</pre>

如果内建语法高亮器均未启用，你可以安装第三方语法高亮插件，也可以使用浏览器端的语法高亮库（例如 highlight.js 和 prism.js 也都支持在浏览器中运行）。

Highlight.js

v7.0.0以下：

# _config.yml
highlight:
  enable: true
  auto_detect: false
  line_number: true
  line_threshold: 0
  tab_replace: "  "
  exclude_languages:
    - example
  wrap: true
  hljs: false
prismjs:
  enable: false

v7.0.0及以上：

# _config.yml
syntax_highlighter: highlight.js
highlight:
  auto_detect: false
  line_number: true
  line_threshold: 0
  tab_replace: "  "
  exclude_languages:
    - example
  wrap: true
  hljs: false

highlight.js 默认开启，用作 Hexo 的服务端高亮组件。如果你需要在浏览器端运行 highlight.js，请把它关闭。

「服务端高亮」指语法高亮在 hexo generate 或 hexo server 时完成。

auto_detect

auto_detect 是 highlight.js 的特性，能够自动检测代码块的语言。

提示：如果你想使用「子语言高亮」功能（例如在高亮 HTML 时同时高亮内部嵌入的 JavaScript 代码），请开启 auto_detect，并且在文章中插入代码块时不要标注语言。

警告！
auto_detect 十分耗费资源。如果你不需要使用「子语言高亮」功能，或者不介意在书写代码块时标记语言，请不要启用此功能。

line_number

highlight.js 不支持行号显示。

Hexo 通过用 <figure> 和 <table> 包裹其代码块为其添加了行号显示支持:

<figure class="highlight yaml">
  <table>
    <tbody>
      <tr>
        <td class="gutter">
          <pre><span class="line">1</span><br></pre>
        </td>
        <td class="code">
          <pre><span class="line"><span class="attr">hello:</span><span class="string">hexo</span></span><br></pre>
        </td>
      </tr>
    </tbody>
  </table>
</figure>

这不是 highlight.js 的行为，因此需要为 <figure> 和 <table> 添加自定义 CSS 代码。部分主题对此提供内建支持。

你大概也注意到了，所有代码块的 class 都没有 hljs- 前缀。我们为此专门准备了一个章节。

line_threshold (+6.1.0)

接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。默认值为 0。

tab_replace

用给定字符串替换代码块内的制表符。默认为 2 个空格。

exclude_languages (+6.1.0)

如果语言符合这个选项，则输出仅仅会被 <pre><code class="lang"></code></pre> 包裹，并且不会在内部渲染所有的标签（span 和 br）。

wrap

为了支持行号显示，Hexo 将输出包裹在了 <figure> 和 <table> 内部。如果要保持 highlight.js 原来的行为，你需要将 line_number 和 wrap 全部关闭。

<pre><code class="yaml">
<span class="comment"># _config.yml</span>
<span class="attr">hexo:</span> <span class="string">hexo</span>
</code></pre>

警告！
%}
Because line_number feature relies on wrap, you can’t disable wrap with line_number enabled: If you set line_number to true, wrap will be automatically enabled.

hljs

当 hljs 设置为 true 时，所有代码块的 HTML 输出均会给 class 添加 hljs- 前缀（无论 wrap 是否开启）：

<pre><code class="yaml hljs">
<span class="hljs-comment"># _config.yml</span>
<span class="hljs-attr">hexo:</span> <span class="hljs-string">hexo</span>
</code></pre>

提示：当 line_number 和 wrap 为 false，hljs 为 true 的时候，你可以在站点上直接应用 highlight.js 的主题。

PrismJS

v7.0.0以下：

# _config.yml
highlight:
  enable: false
prismjs:
  enable: true
  preprocess: true
  line_number: true
  line_threshold: 0
  tab_replace: ""

v7.0.0及以上：

# _config.yml
syntax_highlighter: prismjs
prismjs:
  preprocess: true
  line_number: true
  line_threshold: 0
  tab_replace: ""

PrismJS 默认禁用。启用 PrismJS 前应设置 highlight.enable 为 false（v7.0.0以下）或设置 syntax_highlighter 为 prismjs（v7.0.0及以上）。

preprocess

Hexo 内建的 PrismJS 支持浏览器端高亮（preprocess 设置为 false）和服务器端高亮（preprocess 设置为 true）两种方式。

当 preprocess 与 line_number 均设置为 true 时，只需要引入 prism-line-numbers.css 即可启用行号显示。如果 preprocess 和 line_number 均被关闭，则需要将 prism-line-numbers.css 和 prism-line-numbers.js 都引入才能启用行号显示。

preprocess 设置为 false 时所有 PrismJS 插件均可用，只需额外注意以下几点：

行号显示：需要引入prism-line-numbers.css，无需引入prism-line-numbers.js。 Hexo 将生成其所需的 HTML 代码片段。
语言显示：当代码块有标注语言时，Hexo 总会添加 data-language 属性。
Hexo 也支持其它不需要特殊 HTML 代码格式的 PrismJS 插件，不过你需要引入它们的 JavaScript 文件。

如果 preprocess 设置为 false，则支持所有 prism 插件。以下是您仍需注意的几件事：

行号显示：当 preprocess 设置为 false 时，Hexo 不会生成插件所需的 HTML 代码格式。 prism-line-numbers.css 和 prism-line-numbers.js均需被引入。
语言显示：当代码块有标注语言时，Hexo 总会添加 data-language 属性。
高亮特定行: Hexo 的代码块标签插件和反引号代码块标签插件都支持高亮特定行的语法（即 mark 选项）。当 mark 项被设置时，Hexo 将生成其所需的 HTML 代码格式。

line_number

因为 line_number 功能依赖 wrap，你无法在配置中关闭 wrap 而又开启 line_number。如果你将 line_number 设置为 true 的话，wrap 将被自动开启。

line_threshold (+6.1.0)

接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。默认值为 0。

tab_replace

将代码块内的 \t 替换为给定的字符串。默认为 2 个空格。

其它参考资料

Hexo 语法高亮部分的源码可参见：