WordPress で Cisco IOS を色分け｜HCB の設定手順

はじめに

Cisco の設定例を WordPress で公開すると、コメント行、コマンド、IP アドレスが同じ色で並び、行数が増えるほど設定の区切りを追いにくくなります。コードブロック用プラグインの Highlighting Code Block（以下 HCB）は Prism.js で色分けを行いますが、標準の言語一覧に Cisco IOS は含まれていません。

本記事では、筆者の WordPress＋SWELL＋HCB 環境で Cisco IOS 用の簡易的な言語定義を追加し、色分け表示を確認した手順を紹介します。HCB の設定項目は共通ですが、ファイルの配置例と表示結果は SWELL 環境のものです。

HCB で Cisco IOS を色分けするには、言語セットへの Cisco IOS の登録と、Cisco IOS の定義を含む prism.js の読み込みを両方設定します。筆者の SWELL 環境では、/wp-content/themes/swell/hcb/prism.js にファイルを配置し、「独自 prism.js」欄へ hcb/prism.js と入力して、色分け表示を確認できました。

左が色分けなし、右が今回の独自定義による色分けありの表示です。どちらも同じ 17 行の設定例を、HCB の暗い背景と行番号付きで表示しています。

HCB で Cisco IOS を色分けする仕組み

HCB の色分けは、ブロックで選んだ言語のクラス名と、Prism.js に登録された言語定義の名前が一致したときに適用されます。設定箇所が 2 つに分かれているため、片方だけでは色が付きません。

言語選択肢の登録と言語定義の読み込みは別の作業

HCB は言語セットのキーをクラス名として出力し、Prism はそのクラス名に対応する言語定義を参照します。言語セット側のキーと Prism.languages のプロパティ名は、どちらも cisco にそろえる必要があります。

参考: HCB 公式「Highlighting Code Block の使い方」
「各言語に対応するクラス名は、prism.jsで定められているものを指定してください。」
https://loos.co.jp/documents/highlighting-code-block/

独自 prism.js の読み込み先

HCB の公式手順では、作成した prism.js を有効化しているテーマのフォルダー内へアップロードし、「高度な設定」の「独自 prism.js」にそのファイルまでのパスを入力します。

参考: HCB 公式「Highlighting Code Block の使い方」
「ダウンロードしたファイル（ prism.js ）をあなたが有効化しているテーマフォルダ内にアップロードします。」
https://loos.co.jp/documents/highlighting-code-block/

本記事の HCB の動作に関する説明は、WordPress.org の配布ページから案内されている公式ソースコードのうち、バージョン 2.2.1 の固定コミット（loos_hcb.php、loos_hcb_scripts.php）で確認した内容です。筆者の検証環境のバージョンを示すものではありません。確認した範囲では、次の動作になっています。

• 「独自 prism.js」のパスは、有効化中のテーマのフォルダー URL を基準に組み立てられます。子テーマを有効化している場合は、子テーマのフォルダーが基準です。
• 独自 prism.js を指定すると、HCB 同梱の prism.js の代わりにそのファイルが読み込まれます。
• prism.js は、サイト表示側のスクリプトとして読み込まれます。

筆者の環境では、接頭部分に https://mytech-blog.com/wp-content/themes/swell/ と表示されていました。入力欄には、この接頭部分に続く相対パスだけを入力します。

独自 prism.js に置き換える前の確認事項

前述のとおり、独自 prism.js を指定すると HCB 同梱の prism.js は読み込まれません。新しい prism.js には、Cisco IOS の定義に加えて、既存記事で使っている言語とプラグインを含める必要があります。

Cisco IOS 用の独自 prism.js を作成する

prism.js は、Prism のダウンロードページで本体と必要な言語・プラグインをまとめたファイルを作成し、その末尾に Cisco IOS の定義を追記して用意します。追記するコードは Prism 本体を含まない言語定義だけのため、このコードだけで prism.js を置き換えないよう注意が必要です。

;
Prism.languages.cisco = {
  comment: {
    pattern: /^[ \t]*!.*$/m,
    greedy: true
  },
  description: {
    pattern: /(^[ \t]*description[ \t]+)[^\r\n]+/mi,
    lookbehind: true,
    alias: 'string'
  },
  string: {
    pattern: /"(?:\\.|[^"\\\r\n])*"/,
    greedy: true
  },
  'ip-address': {
    pattern: /\b(?:\d{1,3}\.){3}\d{1,3}(?:\/\d{1,2})?\b/,
    alias: 'number'
  },
  'interface-name': {
    pattern: /\b(?:GigabitEthernet|TenGigabitEthernet|FastEthernet|Ethernet|Loopback|Vlan|Port-channel|Tunnel|Serial)\d+(?:[/.:-]\d+)*\b/i,
    alias: 'builtin'
  },
  keyword: /\b(?:interface|description|hostname|ip|ipv6|address|route|router|network|neighbor|remote-as|ospf|bgp|vlan|switchport|mode|access|trunk|allowed|encapsulation|dot1q|shutdown|no|exit|end|permit|deny|access-list|access-group|remark|line|console|vty|login|transport|input|output|service|spanning-tree|enable|configure|terminal|show|running-config|copy|write|memory)\b/i,
  number: /\b\d+\b/
};

追記した定義が色分けする要素

今回の定義は、表示確認のために用意した簡易定義です。Cisco が提供する Prism 用の定義や、Cisco が動作を保証するコードではありません。ネットワーク設定の色分けは Cisco の開発者向けブログでも Atom エディター向けパッケージの例として紹介されていますが、本記事の定義はそのパッケージとは別に Prism 用に記述したものです。

参考: Prism「Extending Prism」
“the language definition does not control the color of tokens, themes do.”
（言語定義はトークンの色を制御せず、色を決めるのはテーマです。）
https://prismjs.com/extending.html

実際の色は、トークン名と alias に対して HCB やテーマ側の CSS が割り当てます。そのため、分類が異なる要素が同じ色で表示されたり、通常の文字色に近い色で表示されたりする場合があります。

SWELL で HCB に Cisco IOS を追加する設定手順

ここからは、筆者の SWELL 環境で色分け表示を確認できた手順です。配置先は有効化中のテーマによって異なるため、最初に設定画面で接頭部分を確認します。

接頭部分が親テーマのフォルダーを示す場合、テーマの更新時にフォルダーが置き換えられ、追加したファイルが失われる可能性があります。作業前に、作成した prism.js を手元にバックアップとして保管しておくことをおすすめします。

cisco:"Cisco IOS",

筆者の環境での対応関係は次のとおりです。

接頭部分と入力値をつないだ URL が、配置したファイルの URL と一致する必要があります。フォルダー名やファイル名が 1 か所でも異なると読み込めず、一般的な Linux サーバーでは大文字・小文字も区別されます。

入力欄に wp-content/themes/swell/hcb/prism.js のような接頭部分と重なるパスを入れると、テーマフォルダーの下に同じ階層を重ねた URL になり、ファイルを読み込めません。

サンプルで Cisco IOS の色分け表示を確認する

表示確認には、冒頭の比較画像と同じ次の設定例を使います。表示確認用に作成した架空の設定例で、Cisco 機器へ投入して疎通や OSPF の動作を確認したものではありません。

! Cisco IOS highlighting demo
hostname Branch-R1
!
interface Loopback0
 description Router Loopback
 ip address 10.255.0.1 255.255.255.255
!
interface GigabitEthernet0/1
 description Link to Core-R1
 ip address 192.0.2.1 255.255.255.252
 no shutdown
!
router ospf 10
 network 10.255.0.1 0.0.0.0 area 0
 network 192.0.2.0 0.0.0.3 area 0
!
end

冒頭の比較画像の上段では、コメント行、hostname・interface・ip address・no shutdown・network・end などのコマンド、説明文、IP アドレスと数値に色が付いています。一方、area、Branch-R1、インターフェース名、description の語は通常の文字色に近く、router は他のコマンドと異なる色で表示されています。下段は、すべての行が通常の文字色です。

画像の各色がどの CSS の指定によるものかは、本記事では特定していません。自環境で表示が異なる場合も、コメント行、コマンド、説明文、数値が通常の文字と区別されているかを目安に確認します。

Cisco の設定例を多く掲載する記事の例として、当ブログには「Cisco ルーターでの OSPF 設定手順とマルチエリア構成のコンフィグ例」があります。HCB の言語設定はブロックごとに保存されるため、既存記事で Cisco IOS を使う場合は、対象のブロックごとに言語を変更します。

Cisco IOS が色分けされないときの切り分け

色が付かない原因は、症状によって確認先が異なります。まず症状を特定し、次の順序で確認すると原因を絞り込みやすくなります。

簡易定義の制約と継続運用の注意点

今回の定義は、一般的な設定例を読みやすくするための簡易的なものです。掲載するコンフィグの種類と、ファイルの配置場所に応じた注意点を整理します。

簡易定義で扱えない範囲

• Cisco IOS の全コマンド・全構文を網羅するものではありません。
• area など、キーワード一覧にない語は色分けされません。
• 省略形のコマンド、IPv6 アドレス、複数行の banner、プロンプト付きの入力、show コマンドの出力全体は想定していません。
• IP アドレス風の文字列を色分けする処理で、アドレスや設定内容の正しさを検証するものではありません。

対応語の追加や正規表現の変更を行うと、本記事で表示を確認した定義とは別物になります。変更した場合は、変更後の定義でサンプルと既存記事の表示を改めて確認することをおすすめします。

定義を拡張する場合は、Prism の「Extending Prism」にあるトークンの順序と greedy の指針も参考になります。今回の定義では description が string より前にあり、同資料が推奨する「greedy なトークンを先頭にまとめる」配置とは異なるため、トークンを追加・並べ替える際はあわせて確認することをおすすめします。

テーマ更新後の確認

親テーマ内に prism.js を配置した場合は、テーマ更新後に次の点を確認することをおすすめします。ファイルが失われていた場合は、保管しておいたバックアップを同じ場所へ配置し直します。

• ファイル URL が 404 にならないか
• 公開ページで Cisco IOS の色分けが表示されるか
• 既存記事の他言語の色分けと行番号が表示されるか

参考: WordPress Developer Resources「Child Themes」
“Allow parent themes to be updated without losing your modifications.”
（子テーマを使うと、変更内容を失わずに親テーマを更新できます。）
https://developer.wordpress.org/themes/advanced-topics/child-themes/

子テーマの利用は、テーマ更新の影響を分けるための選択肢の一つです。ただし、テーマの切り替えはサイト全体に関わる変更のため、prism.js の配置だけを理由に急いで切り替える必要はありません。

Prism が提供する言語との違い

PowerShell のように Prism が言語定義を提供している言語は、ダウンロードページでチェックを入れて prism.js を作成し、言語セットに Prism のクラス名（PowerShell の場合は powershell）で追加します。Cisco IOS は執筆時点で同ページの言語一覧に見当たらないため、本記事では定義を記述して prism.js の末尾に追記しています。

まとめ

HCB で Cisco IOS を色分けするには、言語セットへの登録と、Cisco IOS の定義を含む prism.js の読み込みを両方設定します。筆者の SWELL 環境では、設定画面の接頭部分が示す親テーマ内に hcb フォルダーを作成して配置し、接頭部分に続く相対パスを指定して表示を確認できました。

• 言語セットの登録と言語定義の読み込みは別の設定です。
• Prism 側の定義名と言語セットのキーは同じ cisco にそろえます。
• 独自 prism.js には既存記事で使う言語とプラグインも含めます。
• 配置先は設定画面の接頭部分を確認してから決めます。
• 入力欄には接頭部分に続く相対パスだけを指定します。
• 色が付かない場合は実際に読み込まれた JS と定義の有無を確認します。
• 親テーマ内に置く場合はバックアップと更新後の確認が大切です。

以上、最後までお読みいただきありがとうございました。