シンタックスハイライト

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 は、コードブロックの言語を自動的に検出する highlight.js の機能です。

ヒント: 「サブラングハイライト」を使用する場合は、auto_detect を有効にして、コードブロックを記述するときに言語を指定しないでください。

警告！

auto_detect は非常にリソースを消費します。「サブラングハイライト」が本当に必要な場合、またはコードブロックを記述するときに言語をマークしたくない場合を除き、有効にしないでください。

行番号

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

プリプロセッシング

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` と `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のシンタックスハイライトの背後にあるソースコードは、次の場所にあります.

前次