個人ブログにシンタックスハイライトを導入した話

Webデザインやアプリ開発の記録を書いていると、ソースコードを掲載する機会が自然に増えていきます。コードが本文の中にそのまま並んでいると、読者はどこからどこまでがコードなのか判断しにくく、長い例ではインデントも見失いがちです。

そこで、ブログの記事にシンタックスハイライトを導入しました。普段の制作記録を掲載しているMimaのブログで、見た目の改善だけでなく、コードを読みやすく保つための投稿方法や運用面も見直しています。

コード掲載で感じていた課題

以前は、コードブロックを枠で囲む程度のスタイルしか用意していませんでした。HTML、CSS、JavaScript、Rubyが同じ色で表示されるため、タグや文字列、コメントの区別がつきにくく、説明文とコードの視線移動にも負担がありました。

特にスマートフォンで記事を読む場合、横幅が限られます。長い行が折り返されるとコードの構造が崩れて見えますし、横スクロールを許可すると画面の操作性が下がります。技術記事として内容を残すには、文章だけでなく表示方法も整える必要がありました。

候補にしたのは、Highlight.jsやPrism.jsのような外部ライブラリと、言語ごとの色をCSSで手作業設定する方法です。自分で配色を管理すれば軽量にできますが、コメントや正規表現など細かな構文への対応を長く維持するのは難しそうでした。

今回は、導入の手軽さと対応言語の多さを重視しました。記事側でコードブロックに言語名を指定し、ライブラリに解析してもらう形なら、新しい言語を試すときも記事の書き方を大きく変えずに済みます。

まずコードブロックに言語を示すクラスを付けます。たとえばRubyならlanguage-ruby、JavaScriptならlanguage-javascriptという形式です。これによって、ハイライト用のスクリプトがコードの種類を判断できるようになります。

次に、必要なJavaScriptとCSSを読み込みます。ページ全体で利用できるよう共通レイアウトに設定しましたが、コードを掲載しないページまで大きなファイルを読み込む点は気になりました。そこで、ファイルサイズと表示速度を確認しながら、利用する言語やテーマを絞っています。

見た目だけを変えても、投稿時に言語指定を忘れると期待どおりに表示されません。そこで、Markdownを書く段階からコードフェンスの後ろに言語名を付けるルールを決めました。記事の下書きでコードを追加した時点で、ハイライトの対象になるか確認しています。

Railsでブログを自作した記録をまとめたブログ制作の記録のように、実装手順を説明する記事ではコードの役割が伝わりやすくなりました。本文中で「この部分を変更します」と書いたときも、色分けされたコードなら対象箇所を見つけやすくなります。

配色は、背景色の濃さと文字色のコントラストを優先しました。暗いテーマは開発者らしい印象を出しやすい一方、本文の白い背景から急に切り替わると圧迫感があります。ブログ全体の余白や角丸の大きさと合わせ、コードだけが目立ちすぎないデザインにしています。

色だけで意味を伝えないことも重要です。コメントやキーワードが同系色でも判別できるよう、文字の太さや記号を確認しました。横幅の広いコードは横スクロールできるようにし、行番号は必須にせず、コピーしやすさを優先しています。

目的やブログの構成によって、適した方法は変わります。更新頻度が低く、掲載する言語も少ない場合はCSSだけでも十分ですが、複数の技術を扱うブログなら専用ライブラリの恩恵が大きくなります。

方法	導入の手軽さ	対応言語	カスタマイズ	向いているケース
CSSのみ	高い	少ない	高い	短いコードを少量掲載する
Highlight.js	高い	多い	中程度	幅広い言語を手軽に扱う
Prism.js	中程度	多い	高い	軽量さと拡張性を両立する
サーバー側処理	低い	構成次第	高い	静的HTMLを安定して生成する

導入後は、過去記事のコードも少しずつ見直しています。言語指定がないブロック、特殊文字が正しくエスケープされていない箇所、スマートフォンで横に広がりすぎる例を確認しました。一度に全記事を修正するのではなく、アクセスの多い記事から対応すると作業量を抑えられます。

今後の運用では、次の点を基準にします。

シンタックスハイライトは、追加した瞬間に完成する機能ではありません。記事を書く人が迷わず使え、読む人がコードの意味を追いやすい状態を維持してこそ、ブログの資産になります。

技術メモや制作記録でコードを扱うなら、まず代表的な記事を一つ選び、表示速度と読みやすさを確認しながら導入してみてください。自分のブログに合う配色と投稿ルールを整えることで、開発の記録を将来も読み返しやすい形で残せます。