シンタックスハイライト

Hexoには、highlight.jsとprismjsの2つのシンタックスハイライトライブラリが組み込まれています。このチュートリアルでは、Hexoの組み込みシンタックスハイライトをテンプレートに統合する方法を紹介します。

記事でのコードブロックの使用

Hexoは、コードブロックを書く2つの方法をサポートしています。タグプラグイン - コードブロックとタグプラグイン - バックティックコードブロックです:

{% 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
```

3番目の構文はMarkdownの囲みコードブロックの構文で、Hexoはそれを拡張してより多くの機能をサポートしています。利用可能なオプションを見つけるには、タグプラグインドキュメントをチェックしてください。

ヒント: Hexoは、対応するレンダラープラグインがインストールされていれば、どの形式で書かれた記事もサポートしています。それがmarkdown、ejs、swig、nunjucks、pug、asciidocなどであってもです。使用された形式に関係なく、これらの3つのコードブロック構文は常に利用可能です。

設定

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のデフォルトのmarkdownレンダラーであるhexo-renderer-markedに使用されています）は、<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の機能です。

ヒント: “sublanguage highlight” を使用したい場合、auto_detectを有効にし、コードブロックで言語を無指定にします。

警告！

auto_detectは非常に多くのリソースを消費します。”sublanguage highlight”が必要でコードブロックに言語を指定しない場合以外、有効にしないでください。

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>内に ラップ します。highlight.jsの元の振る舞いに戻すには、line_numberとwrapの両方を無効にする必要があります:

<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はデフォルトで無効になっています。prismjsを有効にする前に、v7.0.0より前ではhighlight.enableをfalseに設定するか、v7.0.0以降ではsyntax_highlighterをprismjsに設定する必要があります。

preprocess

Hexoの組み込みprismjsは、ブラウザサイド（preprocessをfalseに設定）とサーバーサイド（preprocessをtrueに設定）の両方をサポートしています。

サーバーサイドモード（preprocessをtrueに設定）を使用する場合、ウェブサイトにはprismjsのテーマ（cssスタイルシート）のみロードします。ブラウザサイドを使用する場合（preprocessをfalseに設定）、javascriptライブラリもロードする必要があります。

Prismjsはブラウザで使用するように設計されているため、preprocessモードでは限られたprismjsプラグインのみがサポートされます:

  • Line Numbers: prism-line-numbers.cssのみが必要です。prism-line-numbers.jsをロードする必要はありません。Hexoが必要なHTMLマークアップを生成します。
  • Show Languages: コードブロックに言語が設定されている場合に限り、Hexoはdata-language属性を追加します。
  • 特別なHTMLマークアップを必要としない他のすべてのprismプラグインも同様にサポートされています。プラグインに応じたJavaScriptをロードしてください。

preprocessがfalseに設定されている場合、すべてのprismプラグインがサポートされます。その場合も、いくつか注意点があります:

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のシンタックスハイライティングの背後にあるソースコードは、以下で利用可能です: