語法高亮 | Hexo 繁體中文

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

使用給定的字串替換程式碼區塊內的 Tab。預設為 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 輸出的 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 設定為 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 語法高亮背後的原始碼可在以下位置取得：