语法高亮 | Hexo 中文网

Hexo 内置两个语法高亮库 highlight.js 和 prismjs。本教程向你展示如何将 Hexo 的内置语法高亮集成到你的模板中。

¥Hexo has two built-in syntax highlight libraries, highlight.js and prismjs. This tutorial shows you how to integrate Hexo’s built-in syntax highlight into your template.

如何在帖子中使用代码块

¥How to use code block in posts

Hexo 支持两种编写代码块的方式：标签插件 - 代码块和标签插件 - 反引号代码块：

¥Hexo supports two ways to write code block: Tag Plugin - Code Block and Tag Plugin - Backtick Code Block:

[title] [lang:language] [url] [link text] [additional options]

code snippet

[title] [lang:language] [url] [link text] [additional options]

code snippet

[title] [url] [link text] [additional options]

code snippet

第三种语法是 Markdown 的隔离代码块语法，Hexo 对其进行了扩展以支持更多功能。查看标签插件文档以了解可用的选项。

¥The third syntax is Markdown’s fenced code block syntax, and Hexo extends it to support more features. Check out Tag Plugin Docs to find out the options available.

提示：Hexo 支持以任何格式编写的帖子，只要安装了相应的渲染器插件。它可以是 markdown、ejs、swig、nunjucks、pug、asciidoc 等。无论使用哪种格式，这三个代码块语法始终可用。

¥Tip: Hexo support posts written in any format, so long the corresponding renderer plugin is installed. It can be in markdown, ejs, swig, nunjucks, pug, asciidoc, etc. Regardless of the format used, those three code block syntax will always be available.

配置

¥Configuration

低于 v7.0.0:

¥below 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 的默认配置。

¥The YAML above is Hexo’s default configuration.

已禁用

¥Disabled

低于 v7.0.0:

¥below 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：

¥When both highlight.enable and prismjs.enable are false (below v7.0.0) or syntax_highlighter is empty (v7.0.0+), the output HTML of the code block is controlled by the corresponding renderer. For example, marked.js (used by hexo-renderer-marked, the default markdown renderer of Hexo) will add the language code to the class of <code>:

```yaml
hello: hexo
```

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

当没有启用内置语法高亮时，你可以安装第三方语法高亮插件，也可以使用浏览器端语法高亮（例如 highlight.js 和 prism.js 都支持在浏览器中运行）。

¥When no built-in syntax highlight is enabled, you can either install third-party syntax-highlight plugin, or use a browser-side syntax highlighter (e.g. highlight.js and prism.js both support running in browser).

Highlight.js

低于 v7.0.0:

¥below 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，则需要禁用它。

¥highlight.js is enabled by default and used as server-side highlighting in Hexo; it needs to be disabled if you prefer to run highlight.js on browser-side.

服务器端意味着语法高亮是在 hexo generate 或 hexo server 期间生成的。

¥Server-side means, the syntax highlight is generated during hexo generate or hexo server.

auto_detect

auto_detect 是 highlight.js 的一项功能，可自动检测代码块的语言。

¥auto_detect is a highlight.js feature that detects language of the code block automatically.

提示：当你想使用 “子语言高亮” 时，请启用 auto_detect 并在编写代码块时不要标记语言。

¥Tip: When you want to use “sublanguage highlight”, enable auto_detect and don’t mark language when writing code block.

Warning!
auto_detect 非常耗费资源。除非你确实需要 “子语言高亮” 或不想在编写代码块时标记语言，否则不要启用它。

¥auto_detect is very resource-intensive. Do not enable it unless you really need “sublanguage highlight” or prefer not to mark language when writing code block.

line_number

highlight.js 不支持行号。

¥highlight.js does not support line number.

Hexo 通过将输出封装在 <figure> 和 <table> 内来添加行号：

¥Hexo adds line number by wrapping output inside <figure> and <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；一些主题具有内置支持。

¥It is not the behavior of highlight.js and requires custom CSS for <figure> and <table> elements; some themes have built-in support.

你可能还注意到，所有 class 都没有 hljs- 前缀，我们将重新讨论后一部分。

¥You might also notice that all class has no hljs- prefixed, we will revisit it later part.

line_threshold（+6.1.0）

接受可选阈值，只要代码块的行数超过该阈值，则仅显示行号。默认为 0。

¥Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is 0.

tab_replace

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

¥Replace tabs inside code block with given string. By default it is 2 spaces.

exclude_languages（+6.1.0）

如果语言与此选项匹配，则仅使用 <pre><code class="lang"></code></pre> 封装，并且不会在内容中渲染所有标签（span 和 br）。

¥Only wrap with <pre><code class="lang"></code></pre> and will not render all tags(span, and br) in content if are languages match this option.

wrap

Hexo 将输出封装在 <figure> 和 <table> 内以支持行号。你需要禁用 line_number 和 wrap 才能恢复到 highlight.js 的行为：

¥Hexo wraps the output inside <figure> and <table> to support line number. You need to disable both line_number and wrap to revert to highlight.js‘s behavior:

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

Warning!
因为 line_number 功能依赖于 wrap，所以你不能在启用 line_number 的情况下禁用 wrap:如果你将 line_number 设置为 true，wrap 将自动启用。

¥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 输出都将以 hljs- 为前缀（无论 wrap 是否启用）：

¥When hljs is set to true, all the HTML output will have class prefixed with hljs- (regardless wrap is enabled or not):

<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 theme。

¥Tip: When line_number is set to false, wrap is set to false and hljs is set to true, you can then use highlight.js theme directly in your site.

PrismJS

低于 v7.0.0:

¥below 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+）。

¥Prismjs is disabled by default. You should set highlight.enable to false (below v7.0.0) or set syntax_highlighter to prismjs (v7.0.0+) before enabling prismjs.

preprocess

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

¥Hexo’s built-in prismjs supports both browser-side (preprocess set to false) and server-side (preprocess set to true).

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

¥When use server-side mode (set preprocess to true), you only need to include prismjs theme (css stylesheet) in your website. When use browser-side (set preprocess to false), you have to include the javascript library as well.

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

¥Prismjs is designed to be used in browser, thus under preprocess mode only limited prismjs plugin is supported:

行号：只需要 prism-line-numbers.css，无需在你的网站中包含 prism-line-numbers.js。Hexo 会为你生成所需的 HTML 标记。

¥Line Numbers: Only prism-line-numbers.css is required, No need to include prism-line-numbers.js in your website. Hexo will generate required HTML mark up mark up for you.
显示语言：只要为代码块指定了语言，Hexo 就会始终添加 data-language 属性。

¥Show Languages: Hexo will always have data-language attribute added as long as language is given for the code block.
任何其他不需要特殊 HTML 标记的 prism 插件也受支持，但你必须包含这些插件所需的 JavaScript。

¥Any other prism plugins that don’t need special HTML markup are supported as well, but you will have to include JavaScript required by those plugins.

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

¥All prism plugins are supported if preprocess is set to false. Here are a few things you should still pay attention to:

行号：当 preprocess 设置为 false 时，Hexo 不会生成所需的 HTML 标记。需要 prism-line-numbers.css 和 prism-line-numbers.js。

¥Line Numbers: Hexo won’t generate required HTML mark up when preprocess is set to false. Requires both prism-line-numbers.css and prism-line-numbers.js.
显示语言：只要为代码块指定了语言，Hexo 就会始终添加 data-language 属性。

¥Show Languages: Hexo will always have data-language attribute added as long as language is given for the code block.
行高亮：Hexo 标签插件 - 代码块和标签插件 - 反引号代码块都支持行高亮语法（mark 选项）。当给出 mark 选项时，Hexo 将生成相应的 HTML 标记。

¥Line Highlight: Both Hexo Tag Plugin - Code Block and Tag Plugin - Backtick Code Block supports Line Highlight syntax (mark option). When mark option is given, Hexo will generate the corresponding HTML markup.

line_number

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

¥With both preprocess and line_number set to true, you just need to include prism-line-numbers.css to make line-numbering work. If you set both preprocess and line_number to false, you will need both prism-line-numbers.css and prism-line-numbers.js.

line_threshold（+6.1.0）

接受可选阈值，只要代码块的行数超过该阈值，则仅显示行号。默认为 0。

¥Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is 0.

tab_replace

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

¥Replace \t inside code block with given string. By default it is 2 spaces.

其他有用信息

¥Other useful information

Hexo 语法高亮的源代码位于：

¥The source codes behind Hexo’s syntax highlighting are available in: