Hexo 代碼高亮

Hexo 對 highlight.js 與 prismjs_blank 兩種代碼高亮庫提供內(nèi)建支持。本篇教程將展示如何將 Hexo 的內(nèi)建語法高亮組件整合至你的模板中。

如何在文章中插入代碼塊

Hexo 支持兩種代碼塊寫法——代碼塊標(biāo)簽插件和反引號代碼塊標(biāo)簽插件：

{% 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 對其進(jìn)行了擴(kuò)展，使其支持更多特性。在標(biāo)簽插件文檔中你可以找到可用的選項。

提示：Hexo 支持用任何格式書寫文章，只需安裝相應(yīng)渲染插件即可。不論文章以何種格式書寫（Markdown、EJS、Swig、Nunjuck、Pug、ASCIIDoc），上述三種代碼塊語法總是可用。

配置

# _config.yml
highlight:
  enable: true
  auto_detect: false
  line_number: true
  tab_replace: ''
  wrap: true
  hljs: false
prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ''

以上為 Hexo 的默認(rèn)配置。

禁用

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

當(dāng) highlight.enable 和 prismjs.enable 均為 false 時，代碼塊輸出的 HTML 由相應(yīng)的渲染器控制。舉個例子：marked.js（Hexo 的默認(rèn) Markdown 渲染器 hexo-renderer-marked 由此驅(qū)動）會把語言加入 <code> 標(biāo)簽的 class 中：

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

如果內(nèi)建語法高亮器均未啟用，你可以安裝第三方語法高亮插件，也可以使用瀏覽器端的語法高亮庫（例如 highlight.js 和 prism.js 也都支持在瀏覽器中運行）。

Highlight.js

# _config.yml
highlight:
  enable: true
  auto_detect: false
  line_number: true
  tab_replace: '  '
  wrap: true
  hljs: false
prismjs:
  enable: false

highlight.js 默認(rèn)開啟，用作 Hexo 的服務(wù)端高亮組件。如果你需要在瀏覽器端運行 highlight.js，請把它關(guān)閉。

「服務(wù)端高亮」指語法高亮在 hexo generate 或 hexo server 時完成。

auto_detect

auto_detect 是 highlight.js 的特性，能夠自動檢測代碼塊的語言。

提示：如果你想使用「子語言高亮」功能（例如在高亮 HTML 時同時高亮內(nèi)部嵌入的 JavaScript 代碼），請開啟 auto_detect，并且在文章中插入代碼塊時不要標(biāo)注語言。

警告！auto_detect 十分耗費資源。 如果你不需要使用「子語言高亮」功能，或者不介意在書寫代碼塊時標(biāo)記語言，請不要啟用此功能。

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 代碼。部分主題對此提供內(nèi)建支持。

你大概也注意到了，所有代碼塊的 class 都沒有 hljs- 前綴。我們 為此專門準(zhǔn)備了一個章節(jié)。

tab_replace

用代碼內(nèi)的 tab (\t) 替換為給定值，默認(rèn)值是兩個空格。

wrap

為了支持行號顯示，Hexo 將輸出包裹在了 <figure> 和 <table> 內(nèi)部。如果要保持 highlight.js 原來的行為，你需要將 line_number 和 wrap 全部關(guān)閉。

<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，你無法在配置中關(guān)閉 wrap 而又開啟 line_number。如果你將 line_number 設(shè)置為 true 的話，wrap 將被自動開啟。

hljs

當(dāng) hljs 設(shè)置為 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>

提示：當(dāng) line_number 和 wrap 為 false，hljs 為 true 的時候，你可以在站點上直接應(yīng)用 highlight.js 的主題_blank。

PrismJS

# _config.yml
highlight:
  enable: false
prismjs:
  enable: true
  preprocess: true
  line_number: true
  tab_replace: ''

PrismJS 默認(rèn)禁用。啟用 PrimeJS 前應(yīng)設(shè)置 highlight.enable 為 false。

preprocess

Hexo 內(nèi)建的 PrismJS 支持瀏覽器端高亮（preprocess 設(shè)置為 false）和服務(wù)器端高亮（preprocess 設(shè)置為 true）兩種方式。

使用服務(wù)器端高亮?xí)r（preprocess 設(shè)置為 true），只需要在站點引入 Prismjs 的主題（CSS 樣式表）即可；而使用瀏覽器端高亮?xí)r（preprocess 設(shè)置為 false），需要將 JavaScript 文件也引入。

PrismJS 主要是面向瀏覽器的。因此，在服務(wù)器端高亮模式下只有部分插件可用：

• 行號顯示：需要引入prism-line-numbers.css，無需引入prism-line-numbers.js。Hexo 將生成其所需的 HTML 代碼片段。
• 語言顯示：當(dāng)代碼塊有標(biāo)注語言時，Hexo 總會添加 data-language 屬性。
• Hexo 也支持其它不需要特殊 HTML 代碼格式的 PrismJS 插件，不過你需要引入它們的 JavaScript 文件。

preprocess 設(shè)置為 false 時所有 primejs 插件均可用，只需額外注意以下幾點：

• 行號顯示：當(dāng) preprocess 設(shè)置為 false 時，Hexo 不會生成插件所需的 HTML 代碼格式。prism-line-numbers.css 和 prism-line-numbers.js均需被引入。
• 語言顯示：當(dāng)代碼塊有標(biāo)注語言時，Hexo 總會添加 data-language 屬性。
• 高亮特定行: Hexo 的代碼塊標(biāo)簽插件和反引號代碼塊標(biāo)簽插件都支持高亮特定行的語法（即 mark 選項）。當(dāng) mark 項被設(shè)置時，Hexo 將生成其所需的 HTML 代碼格式。

line_number

當(dāng) preprocess 與 line_number 均設(shè)置為 true 時，只需要引入 prism-line-numbers.css 即可啟用行號顯示。如果 preprocess 和 line_number 均被關(guān)閉，則需要將 prism-line-numbers.css 和 prism-line-numbers.js 都引入才能啟用行號顯示。

tab_replace

用代碼內(nèi)的 tab (\t) 替換為給定值，默認(rèn)值是兩個空格。

其它參考資料

• Highlight.js
• PrismJS

Hexo 語法高亮部分的源碼可參見：

• Highlight.js 工具函數(shù)
• PrismJS 工具函數(shù)
• 代碼塊標(biāo)簽插件
• 反引號代碼塊標(biāo)簽插件