语法高亮

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

如何在文章中插入代码块

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.enableprismjs.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.jsprism.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 generatehexo server 时完成。

auto_detect

auto_detecthighlight.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> 包裹,并且不会在内部渲染所有的标签(spanbr)。

wrap

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

<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_numberwrapfalsehljstrue 的时候,你可以在站点上直接应用 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.enablefalse(v7.0.0以下)或设置 syntax_highlighterprismjs(v7.0.0及以上)。

preprocess

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

preprocessline_number 均设置为 true 时,只需要引入 prism-line-numbers.css 即可启用行号显示。 如果 preprocessline_number 均被关闭,则需要将 prism-line-numbers.cssprism-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.cssprism-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 语法高亮部分的源码可参见: