シンタックスハイライト

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を有効にし、コードブロックで言語を無指定にします。

Warning!

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>
Warning!

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-で接頭辞付きの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プラグインのみがサポートされます:

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

  • Line Numbers: preprocessがfalseに設定されている場合、Hexoは必要なHTMLマークアップを生成しません。 prism-line-numbers.cssとprism-line-numbers.jsの両方が必要です。
  • Show Languages: コードブロックに言語が与えられている限り、Hexoは常にdata-language属性を追加します。
  • highlight.jsはデフォルトで有効になっており、Hexoでサーバーサイドのハイライトとして処理されます。 ブラウザサイドでhighlight.jsを実行する場合、これを無効にする必要があります。

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

Next