14時05分05秒 [Web関連]
シンタックスハイライターPrism.jsの使い方と、必要なときにだけ動的に読み込む方法
シンタックスハイライターとして Prism.js が良さげ
Web上にソースコードを見やすく掲載するシンタックスハイライター(Syntax Highlighter)として以前から利用していたスクリプトがもはや更新されておらず、色分けの仕様が古すぎて最近の書き方に対応できないので、何か新しいスクリプトを使う方が良いだろうな……と思っていました。いろいろ調べたところ、最近は Prism.js というスクリプトが軽量かつ見やすくて良さそうなので、これを使ってみることにしました。
Prism.jsはセットアップも使用も簡単なのですが、CDNサーバでは提供されておらず「加えたいオプションを選択した上でカスタマイズされたファイルをダウンロードして設置する」というやや特殊な方法が採用されています。いや、「特殊」と言うと大げさですが。その分、便利なのですけどもね。備忘録として「Prism.jsのセットアップ方法」と「シンタックスハイライトの方法」を以下に記録しておきます。
Prism.jsのコアはJavaScriptとCSSを合わせても2ファイルで20KB程度しかない軽いスクリプトです。なので、使うかどうかにかかわらず常時読み込んでいても良いかもしれないのですが、無駄な通信は極力省いた方が良いので「シンタックスハイライターが必要な場面でだけ、Prism.jsを動的に読み込む」ために私が採用した方法も、ついでに最後に紹介しておきます。
Prism.jsのセットアップ(設置)STEP：
Prism.js は、JavaScriptファイル1つ「prism.js」と、CSSファイル1つ「prism.css」の計2ファイルだけで動作します。見栄えを決めるテーマ(8種類)や、ハイライト対象の言語(約300種類)や、機能を追加するプラグイン(約30種類)がありますが、それらは個別のファイルとしては提供されていません。
ではどうやってそれらを読み込むかというと、Prism.js公式サイト上で
- テーマ（シンタックスハイライトの配色）を選択し、
- ハイライト言語（PHPとかPythonとか）を選択し、
- 使いたいプラグインを選択
……すると、上記の1～3を含んだJavaScript＋CSSファイルが動的に生成される仕組みになっています。
なので、どんなテーマを選んでも、どんな言語を選択しても、どれだけプラグインを加えても、ダウンロードするファイルは「prism.js」と「prism.css」の2つだけになります。この仕様のために、CDNでは提供されていないのでしょうね。（選択によってファイルの中身が変わるため。）
▼Prism.jsセットアップ(設置)の手順
Prism.jsのセットアップ(設置)に必要な手順は、以下の4つです。最初の「オプション選択」部分だけが独特で、後は特に迷う点はないと思います。
- Prism.jsの公式ウェブで、使いたいオプションを選択する
- 生成されたJavaScriptとCSSファイルをダウンロードする(計2ファイルのみ)
- 自分用のPrism.jsを自サイトに設置する
- シンタックスハイライトしたいページで一式を読み込む
(1) Prism.jsの公式ウェブで、使いたいオプションを選択する
まずは、Prism.jsの公式ウェブサイトにアクセスしましょう。右上にでっかい「DOWNLOAD」ボタンがありますので押します。すると、「Customize your download」というページに移動します。私が試したときには https://prismjs.com/download.html というURLでした。
ここで、「①スクリプトの圧縮状態」と、「②テーマ」と、「③ハイライト対象言語」と、「④プラグイン」を選択します。④は任意ですが、①～③は必須です。
●上図の黄色矢印部分「①スクリプトの圧縮状態」は、「Minified version」を選択しておけば良いです。（ソースを読みたいなら「Development version」にしてダウンロードすれば良いですが、実際に使う場合は余計な空白や改行はない方が良いので「Minified version」一択です。）
●上図の緑色矢印部分「②テーマ」は、使いたいテーマを1つ選択します。テーマ名はリンクになっていて、クリックすると『そのテーマが選択された状態の Prism.jsトップページ』が表示されます。トップページには（Prism.jsを説明するための）サンプルソースが複数掲載されているのですが、それらが指定したテーマで表示されるようになっています。好きな物を1つ選びましょう。トップページ以外の各ページでもテーマを動的に切り替えて見栄えの違いを確認できます。なお、複数のテーマをDLして切り替えて使うような仕様にはなっていないので、どれか1つだけを選択する必要があります。
●上図の水色矢印部分「③ハイライト対象言語」は、色分け表示したい言語を選択します。「Markup + HTML + XML + SVG + MathML + SSML + Atom + RSS」と、「CSS」と、「C-like」と、「JavaScript」は最初から選択されていると思います。そのほか、C++とか、Goとか、PerlとかPHPとかPythonとかRubyとか300種類くらいの選択肢がありますので、必要な言語だけを選択すると良いでしょう。「その言語を加えると何KBの容量が増えるか」も明記されているので親切ですね。
●上図には見えていませんが、最後に「④プラグイン」の追加ができます。私は、行番号を加える「Line Numbers」というプラグインだけを追加しました。長いソースを掲載するときには行番号が表示される方が説明しやすくて便利ですから。そのほかにも、クリップボードにコピーするボタンを表示するプラグインとか、指定行だけをハイライトするプラグインとか30種類くらいが提供されています。どれも軽いですが、さすがに全部を選択するとそこそこのファイルサイズになりますから、必要なものだけを選択すると良いでしょう。
(2) 生成されたJavaScriptとCSSファイルをダウンロードする(計2ファイルのみ)
ダウンロードページを下端までスクロールすると、下図の（紫色矢印の先部分の）ように「動的に生成されたJavaScriptソースとCSSソース」が見えます。また、それらがどれくらいのサイズになっているのかも「Total filesize」として表示されています（水色矢印部分）。
ここに掲載されているソースをそのままコピーしても良いですが、その下にある「DOWNLOAD JS」ボタンと「DOWNLOAD CSS」ボタンを押せば、それぞれの生成ソースが「prism.js」と「prism.css」のファイル名でダウンロードできます。
この2ファイルをローカルにダウンロードしましょう。これが、あなたが選択した内容にカスタマイズされた Prism.js 本体ファイルになります。
▼最後にブラウザのアドレス欄をコピーしておくと便利
このページでの各項目の選択状態は、その都度URLに反映されます。
なので、下図のように（すべて選択し終わった後で）ブラウザのアドレス欄に見えているURLをコピーしておけば、『今の選択内容』を後から再現できて便利です。
後日になってから、別のオプションを加えたくなったり切り替えたくなったりした際には、コピーしておいたURLにアクセスした上で必要な箇所を変更すれば、1からすべてを選択しなおすよりも楽に済むでしょう。
(3) 自分用のPrism.jsを自サイトに設置する
ダウンロードした「prism.js」と「prism.css」の2ファイルは、自サイト内の適当な場所にアップロードします。
これで設置は完了です。
まあ、特に説明することもありませんよね。(^_^;)
(4) シンタックスハイライトしたいページで一式を読み込む
ソースコードを色分け表示したいページで、「prism.js」と「prism.css」の2ファイルを読み込みます。
これも特に説明することはありませんね。link要素とscript要素で読み込めば良いだけです。
HTMLのhead要素内で、以下のようにlink要素を使って「prism.css」を読み込んで、
<link href="prism.css" rel="stylesheet">body要素の最後で、以下のようにscript要素を使って「prism.js」を読み込めば良いだけです。
<script src="prism.js"></script>Prism.js自体はとても軽量なスクリプトで、よほど多数の言語やプラグインを選択しない限りはCSS＋JavaScriptソース全部でも20～30KB程度にしかなりません。とはいえ、どれだけファイルサイズが小さかろうとも「ソースコードを掲載しないページ」でも読み込むのは無駄ですから、私のサイトでは『Prism.jsを必要とするページ』でだけ動的に読み込まれるようにしてみました。その方法は後述します。
Prism.jsを使ってシンタックスハイライトする方法
Prism.jsを使ってソースコードが色分け表示されるようにするには、pre要素をcode要素を使ってソースコードを記述して、それらの要素に必要なclass名を書くだけです。
使い方は、Prism.js公式サイトのHOMEにあるBasic Usage部分にざっと書かれていますので詳しくはそこを見て頂ければ良いのですけども、基本はとても簡単で、以下の2パターンだけ覚えておけば充分だと思います。
▼パターン1：ソースコードが複数行の場合
pre要素のclass名に使用プラグイン名を列挙して、code要素のclass名にlanguage-xxxの形式で言語を記載します。
例えば、言語がHTMLなら、以下のようになります。
<pre><code class="language-html">
～掲載するソースコード～
</code></pre>
例えば、行番号を付加するプラグイン(line-numbers)を使う場合で、言語がHTMLなら、以下のようになります。
<pre class="line-numbers"><code class="language-html">
～掲載するソースコード～
</code></pre>
どのようなclass名が必要なのかは、各プラグインのページに記載がありますので、そこを見て下さい。複数のプラグインを適用する場合は、半角空白で区切って列挙すれば良いです。（適用プラグインを示すclass名は、pre要素に付加せずに、body要素等の親要素に一括指定しても構いません。Prism.jsの公式サイトでは「body要素のclass属性」に指定されています。全ソースで同じプラグインを使いたい場合は、その方法が楽で良いでしょうね。私の場合は、「行番号を付加したい場面」と「行番号を付加したくない場面」とが混在しますので、毎回pre要素に使用プラグイン名を指定する書き方を採用しました。
さらに、Prism.jsで装飾される範囲に独自の装飾を加えたいなどの都合がある場合は、pre要素に（例えば）「prism」などの任意のclass名を加えておけば良いでしょう。
<pre class="prism line-numbers"><code class="language-html">
～掲載するソースコード～
</code></pre>
上記のように、（Prism.js側では要求されていない）任意のclass名を加えても、特に問題なく動作してくれます。
▼パターン2：ソースコード1行をインラインに掲載する場合
文章中に（インラインで）掲載するソースコードを色分け表示したい場合は、pre要素を使わずにcode要素だけで記述します。そのcode要素のclass名にlanguage-xxxの形式で言語を記載します。
<code class="language-css">p { color: red }</code>簡単ですね。
- 複数行ソースなら pre＋code要素
- インライン掲載なら code要素だけ
……という書き方です。
まあ、あえて説明しなくても「普通そう書くだろう」とは思いますが。要するに、Prism.js用の特殊なマークアップ方法は(class名以外には)必要なく、わりと普通の書き方をするだけで色分け表示してくれる、ということです。
▼HTML中にCSSやJavaScriptが登場するソースを色分けさせたい場合の言語指定
code要素にはclass名で「何の言語だと解釈して色分け表示するのか」を指定する必要がありますが、言語って1種類に限定できるとは限りませんよね。例えば、HTMLソースを掲載する場合、そのHTMLソースの中にCSSソースやJavaScriptソースが含まれることはよくあります。
その場合は、class="language-html"のように、HTMLを言語として指定しておくだけでOKです。
言語はHTMLに設定していても、そのソース中に登場するstyle要素の中身はCSS用に色分けされ、script要素の中身はJavaScript用に色分けされます。便利！
下記は、HTMLソースの中にCSSソースとJavaScriptソースも含む例で、言語指定はHTMLだけ（<pre class="line-numbers"><code class="language-html">～</code></pre>）で表示した例です。
<!DOCTYPE html>
<html>
<head lang="ja">
<meta charset="utf-8">
<title>色分けの言語指定をHTMLにしていても</title>
<style>
div.sample::before {
content: 'style要素内はCSSとして色分けされ';
display: inline-block;
color: darkgreen;
}
</style>
</head>
<body>
<div class="sample">……</div>
<script>
let msg = 'script要素内はJavaScriptとして色分けされます。';
function first() {
alert(msg);
}
first();
</script>
<p class="end">こんな感じで。</p>
</body>
</html>
私は淡い色が好きなので、これまではソースコードもそんな感じで掲載してきたのですけども、ソース部分はむしろ明確に本文と分離して見えるように、暗色スタイルで掲載する方が分かりやすい（見やすい）気が最近はしています。ので、Prism.js公式で提供されている「Tomorrow Night」というダークテーマを採用してみました。上記のサンプルHTMLソースもそれを使って表示されています。使い続けるかどうかは分かりませんけども、しばらくはこれを使ってみます。 ……と思ったのですが、ソースだけが暗色だと「見出し」よりも目立ってしまう問題があってページ構造を把握しにくそうなので、明色にしました。^^; 今は「Coy」というテーマを採用しています。後述しますが、Prism.jsではテーマを切り替える際にHTML側の修正は不要で、単にPrism.jsファイルの構成を変更するだけで良いので、テーマの変更はファイルを置き換えるだけで済むので簡単そうです。
以上、Prism.jsを使ってソースコードを色分け表示する方法でした。
シンタックスハイライターが必要な場面でだけ、Prism.jsを動的に読み込む方法
さて、Prism.js自体はとても軽量なスクリプトですが、どれだけファイルサイズが小さかろうとも「ソースコードを掲載しないページ」でも読み込むのは無駄です。そこで、私のサイトでは『Prism.jsを必要とするページ』でだけ動的に読み込まれるようにしてみました。
方法は簡単で、以下の2ステップだけです。
▼1. 事前にpre要素にprismクラスを付与しておく
「ここのソースコードはPrism.jsでシンタックスハイライトする」という何らかの目印がないと判断できないので、『Prism.jsを使ってシンタックスハイライトしたいpre要素にはprismクラスを付加する』という前提を用意しておきます。
つまり、Prism.jsを適用したいソースは、以下のようにHTMLを書くことにします。
<pre class="prism プラグイン名"><code class="言語名">
～掲載するソースコード～
</code></pre>
このようにすると、
- 【前提条件】prismクラスがWebページ内に含まれている場合にだけ、
- 【動作】「prism.js」と「prism.css」を読み込む
……というようにスクリプトを書いておくことで、Prism.jsを必要とする場面でだけ動的に読み込めるようにできます。
▼2. prismクラスが存在する場合だけ「prism.js」と「prism.css」を動的に読み込むJavaScriptを書く
全ページで読み込まれるJavaScriptファイルに、以下のスクリプトを書いておくだけです。
下記ソース内の /設置場所/prism.css(6行目) や /設置場所/prism.js(10行目) は、実際にファイルを置いた場所に合わせて書き換えて下さい。
// Webページ内に「class="prism"」の指定されたpre要素が存在すれば
if( document.querySelector('pre.prism') ) {
// ▼CSSファイルを動的に読み込む
var pmcss = document.createElement('link');
pmcss.rel = 'stylesheet';
pmcss.href = '/設置場所/prism.css';
document.head.appendChild(pmcss);
// ▼ファイルJavaScriptファイルを動的に読み込む
var pmjs = document.createElement("script");
pmjs.src = "/設置場所/prism.js";
document.body.appendChild(pmjs);
}
※このスクリプトは、HTMLが読み込み終わってから実行されるような位置に記述しておく必要があるので注意して下さい。
軽量スクリプトで見やすく表示できるPrism.js
うちのサーバにあるファイルのタイムスタンプから考えて、前回にシンタックスハイライターを選択したのは2010年だったようです。12年前……！ 当初からそんなにアップデートされていなかった気がしますが、今では配布サイト自体が消滅してしまっています。古いスクリプトのままだと、新しい文法仕様とか新しいプロパティとかが正しく色分けされないので、ちょっと見た目に問題があるのですよね。さすがに何か新しいスクリプトに置き換えないといけないよな……というようなことは数年前から思っていたのですが。(^_^;)
一時期、Googleがシンタックスハイライトサービスを提供していたこともあって、それを呼び出して使えば良いかな……となんとなく検討していた時期もあったのですが、今ではそのサービスも終わってしまったようです。やはり、外部サーバから呼び出して使うサービスは「終了リスク」があるので望ましくないですね。
Prism.jsは、軽量なスクリプトを自サイト内に設置して使えるので望ましい形態でしょう。見栄えもなかなか良さそう（分かりやすそう）なので、しばらくはPrism.jsを使ってみるつもりです。
ただ、既存の（古いシンタックスハイライターを呼び出している）ページを一括して書き換えるのが少々面倒なのでまだ作業できていないのですけども。(^_^;;;
というわけで、Prism.jsを使うための備忘録でした。
