语法高亮

Hexo 内置了两个语法高亮库：highlight.js 和 prismjs。本教程将向您展示如何将 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 的围栏代码块语法，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: ""

以上 YAML 是 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-renderer-marked 使用，Hexo 的默认 markdown 渲染器）将语言代码添加到 <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 的一项功能，它可以自动检测代码块的语言。

提示：当您想使用“子语言高亮”时，请启用 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> 中以支持行号。您需要禁用 两者 line_number 和 wrap 以恢复到 highlight.js 的行为

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

因为 line_number 功能依赖于 wrap，所以您不能在 line_number 启用时禁用 wrap：如果将 line_number 设置为 true，则会自动启用 wrap。

hljs

当 hljs 设置为 true 时，所有 HTML 输出将具有以 hljs- 为前缀的 class（无论 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 设置为 false，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 默认禁用。您应该将 highlight.enable 设置为 false（v7.0.0 之前）或将 syntax_highlighter 设置为 prismjs（v7.0.0 及更高版本），然后才能启用 prismjs。

preprocess

Hexo 的内置 prismjs 支持浏览器端（preprocess 设置为 false）和服务器端（preprocess 设置为 true）。

当使用服务器端模式（将 preprocess 设置为 true）时，您只需要在网站中包含 prismjs 主题（css 样式表）。当使用浏览器端（将 preprocess 设置为 false）时，您还需要包含 javascript 库。

Prismjs 被设计为在浏览器中使用，因此在 preprocess 模式下，仅支持有限的 prismjs 插件

  • 行号：只需要 prism-line-numbers.css，不需要在网站中包含 prism-line-numbers.js。Hexo 会为您生成所需的 HTML 标记。
  • 显示语言：只要代码块提供了语言，Hexo 就会始终添加 data-language 属性。
  • 任何其他不需要特殊 HTML 标记的 prism 插件也受支持，但您需要包含这些插件所需的 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

将 preprocess 和 line_number 都设置为 true 时，您只需要包含 prism-line-numbers.css 即可使行号功能正常工作。如果您将 preprocess 和 line_number 都设置为 false，则需要 prism-line-numbers.css 和 prism-line-numbers.js。

line_threshold (+6.1.0)

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

tab_replace

用给定的字符串替换代码块中的 \t。默认情况下为 2 个空格。

其他有用信息

Hexo 的语法高亮背后的源代码位于