爆速技術ブログに Shiki でシンタックスハイライトを入れた理由

はじめに

このブログでは、できるだけ軽く、速く、読みやすい技術ブログを目指している。

基本方針はシンプルだ。記事本文は静的なHTMLとして出し、初回表示に不要なJavaScriptを絡めない。装飾や機能を増やすときも、それが本当に読む体験に必要かを考えるようにしている。

その方針の中で、今回 Shiki を使ってシンタックスハイライトを導入した。

最初は、シンタックスハイライトを入れるべきか少し迷っていた。

このブログは「爆速」を意識しているため、便利そうだからという理由だけでライブラリを追加したくなかった。コードブロックも、短いものであればプレーンテキストのままでも読める。

ただ、技術ブログを書いていく以上、コードや設定ファイルは避けられない。Astro、TypeScript、CSS、Cloudflare Workers、GitHub Actions などの記事では、複数行のコードや設定例を載せることになる。

そのときに、すべて単色のコードブロックだと視線の移動が増える。キーワード、文字列、コメント、プロパティの境界が分かりにくくなり、本文よりもコードを読む負担が大きくなる。

技術ブログにおいて、コードは本文の補足ではなく、理解を支える重要な情報である。であれば、必要最低限のシンタックスハイライトは読みやすさのために入れる価値があると判断した。

シンタックスハイライトの候補としては、Prism.js や highlight.js のような選択肢もある。軽量さだけを見れば、それらを選ぶ考え方もある。

それでも今回は Shiki を選んだ。

理由は、ビルド時にハイライト済みのHTMLを生成する方針と相性が良かったからだ。

このブログでは、記事本文をクライアント側で組み立てない。Markdownをビルド時にHTMLへ変換し、ブラウザにはできるだけ完成済みのHTMLを渡す。Shiki はこの考え方に合っている。

ブラウザ上でコードを解析して色を付けるのではなく、事前にハイライトしたHTMLを配信できる。つまり、読者が記事を開いたあとに、シンタックスハイライトのためだけに余計なJavaScriptを実行しなくてよい。

「コードを読みやすくしたいが、初回表示の負荷は増やしたくない」という今回の要件には、Shiki がちょうどよかった。

最初は、必要最低限のシンタックスハイライトを自作することも考えた。

たとえば、TypeScriptやJSONだけを対象にして、正規表現でキーワードや文字列に色を付けるくらいなら作れそうに見える。

しかし、実際にはすぐに限界が来る。

JavaScript、TypeScript、CSS、HTML、JSON、YAML、Shell などを扱い始めると、言語ごとの構文差を無視できなくなる。コメント、文字列、テンプレートリテラル、ネスト、エスケープ、属性、設定ファイル特有の書き方など、考えることが多い。

中途半端な自作ハイライトは、軽く見えても保守コストが高い。表示が少し崩れるたびに直す必要があり、記事を書く時間よりもハイライトの調整に時間を使ってしまう可能性がある。

このブログで大事にしたいのは、仕組みを作り込むことではなく、学習や開発の記録を読みやすく残すことだ。その目的から考えると、構文解析は Shiki に任せる方が自然だった。

このブログでは、依存関係を増やしすぎないことを意識している。

ライブラリを1つ追加すると、サイズだけでなく、アップデート対応、設定、互換性、セキュリティ確認も増える。特にクライアント側に入る依存は慎重に見たい。

ただし、依存関係をゼロにすることが目的ではない。必要な機能まで無理に自作して、品質や保守性を落とすのは本末転倒である。

今回の Shiki は、導入する理由が明確だった。

この条件を満たしているなら、依存関係を1つ増やす価値はある。

Shiki を入れるからといって、何でも盛るつもりはない。

このブログでは、あくまで静的で軽い記事ページを保ちたい。そのため、シンタックスハイライトも次の方針で扱う。

大事なのは、Shiki を入れること自体ではない。コードを読みやすくしながら、ブログ全体の軽さを壊さないことである。

爆速な技術ブログを作るうえで、機能を足す判断は意外と難しい。

軽さだけを見れば、何も入れないのが一番だ。しかし、技術記事として読みづらくなってしまうなら、それは良いブログとは言えない。

今回 Shiki を導入したのは、見た目を豪華にするためではない。コードを自然に読めるようにしつつ、クライアント側の負荷を増やさないためである。

速く、軽く、読みやすく。

このバランスを崩さない範囲で、必要なものだけを慎重に選んでいきたい。