シンタックス・ハイライト・ライブラリ「highlight.js」の使い方

highlight.js の使い方について説明します。

1. highlight.js とは？
2. highlight.js の使い方
3. 後から言語を追加する
4. CDN を使って highlight.js を導入する
- 利用手順
- Tips
5. おわりに

1. highlight.js とは？

highlight.js は、Webページ上に表示したプログラミングコードなどに色を付ける（ハイライト）ための JavaScript ライブラリです。

多くの言語に対応しており、スタイル（色）も数多く用意されています。

例えば、以下のように色を付けることができます。

2. highlight.js の使い方

highlight.js は CDN で使う方法も用意されていますが、本ページではライブラリであるファイルを自分でサーバーにアップロードして HTML に組み込むやり方について説明します（本記事の終わりの方で、CDN を利用した導入についても少し追記しました）。

※ CDN で用意されている JavaScript ファイルは、限られた言語しか組み込まれていないため、それ以外の言語を組み込む場合に面倒なのです。

1. ライブラリファイルを取得する

Getting highlight.js にアクセスします。

「Custom package」のところから見ていき、必要な言語にチェックを入れていきます。

[Download] ボタンを押して、ファイルをダウンロードします。

2. 必要なファイルをサーバーにアップロードする

圧縮されたファイルがダウンロードされますので解凍します。

必要なファイルは、以下の2つのみです。

highlight.pack.js ファイル
styles フォルダ内の CSSファイルのうちどれか1つ

highlight.js demo というデモページが用意されているので、ここで好みのスタイルを探すことができます。

スタイルが決まったら、2つのファイルを、ウェブサーバーにアップロードします。

3. ライブラリを適用する作業

HTML ファイル内から、2つのファイルを読み込ませます。

※ ここでは、スタイルとして Monokai を採用したとします。

CSS ファイルの読み込み

<link rel="stylesheet" href="path/to/monokai.css">

JavaScript ファイルの読み込み

<script src="path/to/highlight.pack.js"></script>

また、画面ロード時に highlight.js の処理を開始させる JavaScriptコードを、どこかに記述する必要があります。

<script>hljs.highlightAll();</script>

※ バージョン 10.5 までは以下のコードでした。

<script>hljs.initHighlightingOnLoad();</script>

4. HTML にコードを書く

HTML のコンテンツとして、ハイライト表示したいコードを記述します。

コードの表示に highlight.js を適用させるには、<pre> と <code> で囲む必要があり、<code> の class 属性には、highlight.js で適用する言語名を指定します。この指定がなくても、自動で検知してくれるのですが、間違うこともあるため、指定しておいた方が確実です。

例えば、HTML のコードを書いたのであれば、”html” というクラス名を指定します。

<pre><code class="html">...</code></pre>

複数行ある場合は、1行目は <code> タグの後で改行せずに書かないと余分な1行が表示されてしまいますので注意しましょう。

<pre><code class="html">1行目は改行せずに書いて下さい。
2行目以降は普通に改行してよいです。
3行目
  ：
</code></pre>

また、コード内に “<” や “>” など、HTML において特別な意味を持つ文字がある場合は、文字参照で書く必要があります。

& → &
" → "
' → '
< → <
> → >

5. highlight.js の CSSクラスが適用されているか確認する

このページをウェブブラウザで表示すれば、ハイライト表示されるはずですが、念の為ちゃんと CSSクラスが適用されているか確認します。

例えば、Chrome ブラウザを使っているのであれば、以下の手順で確認できます。

デベロッパーツールの [Elements] タブを開きます（）。
のアイコンをクリックします（下画面参照）。
コードを表示している部分をクリックします（）。
のように、code タグが選択されます。
この状態で、の [Sstyles] タブを開きます。
にあるように、monokai.css ファイルで定義された .hljs クラスが適用されていることが分かります。

6. highlight.js のオブジェクトに、目的の言語が組み込まれているか確認する

ここでも Chrome ブラウザのデベロッパーツールを使い、highlight.js のオブジェクトに、目的の言語が組み込まれているか確認します。

[Console] タブを開き、以下を入力して実行すると、現在使用している highlight.js のオブジェクトに組み込まれている言語一覧が出力されます。

hljs.listLanguages()

<code> タグの class属性に指定した言語名が含まれていれば問題ありません。

もし含まれていないのであれば、Getting highlight.js でその言語にチェックを入れるのを忘れている可能性があります。

3. 後から言語を追加する

後から言語を追加する場合は、「1. ライブラリファイルを取得する」から作業をやり直します。サーバーにアップロードしてある highligh.pack.js ファイルを更新することになります。

「6. highlight.js のオブジェクトに、目的の言語が組み込まれているか確認する」の作業を忘れないようにしましょう。

4. CDN を使って highlight.js を導入する

Web で広く使用されているライブラリファイルは、CDN と呼ばれるネットワークを利用したサーバー上に設置されていることが多く、highlight.js のCSSファイルとJavaScriptファイルもこの CDN を利用することができます。CDN は世界中から高速で利用できるように最適化されています。

利用手順

(1) Getting highlight.js の「Hosted」のところに記述されているコードを HTML の <head> 要素内に貼り付けます。

cdnjs と jsdelivr という2つの CDN を利用した HTMLコードがそれぞれ用意されています。どちらでもよいです。

(2) 今貼り付けたコードのすぐ下に、以下の <script>タグを記述します。

<script>hljs.highlightAll();</script>

※ バージョン 10.5 までは以下を記述していました。

<script>hljs.initHighlightingOnLoad();</script>

(3) シンタックスハイライトしたいコードを、<pre><code> と </code></pre> で囲んで記述します。

JavaScriptコードであれば、こんな感じです。

<pre><code>window.addEventListener('DOMContentLoaded', (event) =&gt; {
  console.log('DOM fully loaded and parsed');

  document.querySelector('#btn1').addEventListener('click', () =&gt; {

  });
});
</code></pre>

最初の <pre><code> のすぐ後ろは改行せずに、そのままコードを記述します。そうしないと空行が表示されてしまいます。
HTML において特別な意味を持つ文字は、「文字参照」で記述します。上記コード中でいうと、「>」という文字は「>」と記述しています。

Tips

適用するプログラミング言語を明示的に指定する

記述したコードに対して、シンタックスハイライトを適用するプログラミング言語を明示的に指定する場合は、<code>タグの class属性にプログラミング言語の名前を指定します。

例えば、JavaScript であれば以下のように指定します。

<pre><code class="javascript">console.log('1行目！')
console.log('2行目！')
console.log('3行目！')
</code></pre>

プログラミング言語の名前は、highlight.js/src/languages GitHub にあるファイル名になっています。
上の方でも説明しましたが、ブラウザのコンソールを開き、hljs.listLanguages() というコードを実行すると、現在適用できるプログラミング言語の名前が一覧表示されます。

デザインの変更

デザインを変更するには、CSS の URL内末尾にある「ファイル名」の部分を変更します。

どんなデザインがあるかは、highlight.js demo で確認できます。
デザインに対応するファイル名は、highlight.js/src/styles GitHub を見るとだいたい分かります。デザイン名に近いファイル名を探してください。
Monokai というデザインであれば、URL内の「default.min.css」を「monokai.min.css」に変更します。

対応するプログラミング言語を変更する

デフォルトの highlight.min.js には、基本的なプログラミング言語しか入っていません。

JavaScriptファイルURLの末尾にあるファイル名を「languages/{言語名}.min.js」に変えることで、特定のプログラミング言語用のJavaScriptファイルを指定することができます。
プログラミング言語に対応するファイル名は、highlight.js/src/languages GitHub で探してください。