アカベコマイリ

HEAR NOTHING SEE NOTHING SAY NOTHING

WordPress に Markdown と highlight.js を導入

ここ数年 Markdown で資料を作成する機会が増えたのでブログもこれで書きたくなった。Markdown なら対応エディタも多くて可搬性が高い。また WordPress から別の CMS へ移行しやすくなるだろう。例えば Hugo のような静的サイト ジェネレーターなど。

このブログではプログラミングについて扱うことが多いので、ソース コードの構文強調も重要である。これまでは機能性から SyntaxHighlighter Evolve を利用していたが、ES2015 や Stylus など最近、登場する機会の増えた言語がサポートされていないので、こちらも乗り換えを検討したい。

Jetpack の Markdown 機能を利用する

WordPress を Markdown 対応させるプラグインはいくつかあるが、信頼性とサポートを考慮して Jetpack を採用することにした。

このプラグインは WordPress.com が提供しており WordPress の管理画面でもインストールを促されるので気になっていた。既にアクセス解析で利用している WordPress.com Stats も Jetpack に含まれているらしく、追加インストールした場合は Jetpack 側の Site Stats が有効化されて継続利用できる。

インストールはプラグインの管理画面から Jetpack を検索して実行すればよい。Site Stats 機能などを利用する場合はインストール後に WordPress.com との連携を設定。要 WordPress.com アカウント。私は Stats 用に設定済みだったから連携の有効化だけで済んだ。

Jecpack は非常に多機能だが、それらは個別に有効化する必要がある。WordPress 管理画面に Jecpack という項目が追加されているので、その中の設定を選ぶ。すると利用可能な機能一覧が表示されるので Markdown を有効にする。

これで Markdown が使えるようになったはず。試しに適当な記事を作成してからテキスト モードで

## 見出し

段落 1

段落 2

のように書いてプレビューすれば HTML 化されることを確認できる。

Markdown と WordPress 記法の混在

これからブログを始めるなら問題ないが既に WordPress 記法で大量の記事がある場合、Markdown との互換性が気になるだろう。Jetpack の Markdown 機能はこのような状況も考慮されており WordPress 記法と混在可能である。

Markdown は WordPress 記法に機能追加されるようで

<h2> WordPress 記法 ( HTML タグ ) の見出し</h2>

## Markdown の見出し

と書けばどちらも <h2> として出力される。もちろん WordPress のショートコードもそのまま動作する。ソース コードの構文強調も SyntaxHighlighter Evolve や WP Code Highlight.js などのプラグインを利用可能。そのため Markdown として構文強調をそのまま記述すればよい。

以上を踏まえ新しい記事は Markdown で書き、時間があれば少しずつ過去記事を Markdown 化してゆく予定。

localhost で Jetpack を利用する

私は自分のブログ用に WordPress テーマやプラグインを開発しており、動作確認は Vagrant + VirtualBox + Varying-Vagrant-Vagrants/VVV を利用している。この環境も本番と同等にするため Jetpack を動かしたい。しかし Vagrant 上の VM は localhost になるため Jetpack を有効にすると XML-RPC エラーが発生する。

これを回避するには Jetpack を開発モードで動作させる。その手順は以下。

  1. Jetpack を VM 上の WordPress にインストール
  2. WordPress 管理画面のメニューからプラグインを選択
  3. プラグイン一覧の Jetpack by WordPress.com から編集を選択
  4. jetpack/jetpack.php が対象になっていることを確認
  5. ファイルの末尾行define( 'JETPACK_DEV_DEBUG', true ); を追加
  6. ファイルを更新ボタンを押して編集内容を保存

これで localhost でも Jetpack を利用可能になる。開発モードだと Stats などの連携が無効になるそうだが、この用途であれば不要なので問題ない。

WP Code Highlight.js で highlight.js を利用する

highlight.js という JavaScript 製の構文強調ライブラリがある。これを WordPress で利用する場合、テーマの function.php で指定する方法が考えられる。しかしこれではライブラリが更新される都度、テーマ修正が発生して面倒だ。

もう少しスマートに運用するなら Header and Footer を利用する方法もある。このプラグインは記事のヘッダーやフッターにテキストを挿入するものでブログ パーツの動的な追加にも利用可能。私も以前 Zenback を埋め込むために採用していた。これで highlight.js の CDN を参照する script タグを挿入すれば、更新をここで管理できる。

しかしどちらの方法も素の highlight.js を利用するため、記事内で構文強調する場合は HTML として書かなくてはならない。

<pre><code class="js">
// 構文強調するコード
</code></pre>

これは面倒だし前述の Markdown による構文強調と組み合わせたいので WP Code Highlight.js を利用する。これは SyntaxHighlighter Evolve における SyntaxHighlighter と同じく highlight.js を WordPress 向けに wrap してくれる。

使用方法は簡単。プラグイン管理画面から WP Code Highlight.js で検索して、その結果からインストール & 有効化すればよい。これだけで Markdown の構文強調が解析対象になる。

このプラグインが提供する機能をまとめてゆく。

CDN

highlight.js の参照方法を変更。各種 CDN サイトとプラグイン組み込みの local から選べる。通信量と Web ブラウザのキャッシュを考慮するなら CDN にする。私は local にした。負荷はあまり気にしておらず、組み込みで固定バージョンを利用するほうが好みなので。

Package

構文強調の対象となる言語を選択。v0.5.9 時点では以下がリストされている。

  1. Common (about 42KB)
  2. All (about 393KB)
  3. Custome

大抵は 1 で十分、今後の言語追加に備えるなら 2。1 に対して個別に言語を追加したいなら 3。私は Stylus だけ欲しかったので 3 にした。CDN 利用なら負荷分散できるので 2 を選ぶのがよいかも。

対象言語は Common 24 + Other 123 で合計 147 もある。かなりマイナーな言語も含まれているうえ SwiftKotlin など最近の言語が採用されていたり、JavaScript における ES2015 など新しい仕様にも対応しており安心感がある。

Color Scheme

構文強調の外観を選択。公式サイトの highlight.js demo にプレビューがあるので好みの外観を探そう。私は Tomorrow Night にした。

Highlight.js Option

構文強調の細かいオプション。いまのところ利用していない。以下の設定値がある。プラグインのページに説明が見当たらないので内容は名称や動作からの予想。

オプション 内容
Tab replace タブ文字の置換対象となる文字列を指定する。
Class prefix CSS クラスの接頭語を指定する。WordPress テーマ側の code タグ指定と競合を避けるための機能だろうか?
Use BR 改行コードを BR タグに変換する。
Languages 用途不明。この言語というのはプログラミング言語なのか、それとも ISO 639 のような現実世界の言語なのだろうか。

You can add some additional CSS rules for better display

構文強調の CSS を独自に拡張。私は標準のままにしている。

他のプラグインとの互換設定

WordPress で普及している構文強調系プラグインの構文サポート。WP Code Highlight.js に移行した場合、これらをチェックすることで既存の記事を従来の記法で構文強調できるらしい。以下の設定がある。

  • Syntax Highlighter Compatiable
  • Prettify Compatible
  • Crayon Syntax Highlighter Compatiable

Syntax Highlighter Compatiable を有効にした状態で SyntaxHighlighter Evolved を無効にしてから以下の構文強調を試したが、無視された。

[html]
<div>テスト</div>
[/html]

では SyntaxHighlighter Evolved と WP Code Highlight.js が両方とも有効ならどうか?と試したら、HTML タグの不等号などが構文強調の中で文字実体参照に変換されてしまった。

この設定を正しく動作させる方法がわからないので、利用するのはやめておく。

Enable [code] code content ...[/code] support

ショートコードの code 記法を対象とする設定。SyntaxHighlighter Evolved では code + lang で書く方法もあり、これが有効になる。

[code lang="js"]
const test = "test";
assert(test);
[/code]

JavaScript などは動作するが HTML はタグなどをエスケープしないと正しく描画されない。

SyntaxHighlighter Evolved から WP Code Highlight.js への移行

WP Code Highlight.js には SyntaxHighlighter Evolved の互換設定があるものの前述のように正しく動作させられなかった。SyntaxHighlighter Evolved 用の構文強調は大量にあるため、いますぐ移行するのは厳しい。

ま機能面でみると行番号と行の強調が失われる。highlight.js としては、強調したい行があるならその部分だけ抜粋すればよいという思想らしく今後も変わることはないだろう。

とはいえ対応言語と最新仕様への対応は魅力的。そのため以下のように移行計画を立てた。

  • 過去記事の構文強調をすべて Markdown 化する

    • この対応で SyntaxHighlighter Evolved のショートコードも Markdown 化される
    • Markdown にしても構文強調は動作する
  • 過去記事で行番号の強調に頼る記述を依存しないものへ修正する

    • 強調・ハイライトしている部分が云々、という 記述の修正
    • 構文強調は抜粋にする
  • Markdown 化が完了したら SyntaxHighlighter Evolved を無効化、WP Code Highlight.js を有効化

    • Markdown の構文強調を処理するプラグインが変更されるだけ
    • 安全に切り替えられる

このブログは記事数こそ少ないが個々の内容は長いため気の長い作業になるだろう。さすがに手動でやるのは辛いのでエディタの置換なりスクリプトなどで処理する予定。

Comments from WordPress

  • Yousan Yousan 2017-08-05T23:39:52Z

    記事ありがとうございます。参考になります。

    文中の一部、codeタグがcpdeになっていました。

    // 構文強調するコード
    </code>

    ご参考までに。

  • アカベコ アカベコ 2017-08-06T03:52:36Z

    ご指摘ありがとうございます。文中の typo を修正しておきました。