2025/01/06

【公式ライブラリ使用】microCMS でシンタックスハイライトを簡単実装する方法

📑 目次

こんにちは、KnowHack（ノウハック）です。

今回は microCMS が公式で公開しているリッチエディタ向けライブラリ を使って、シンタックスハイライト機能を簡単に実装する方法を紹介します。

microCMS-rich-editor-handler は、画像最適化・シンタックスハイライト・目次生成などがサクッと実現できる便利ツール。使いたい機能だけオプションで有効化できるため、段階的に導入できるところも魅力です。

公式ドキュメント: microcms-rich-editor-handler

今回の記事では、シンタックスハイライト機能にフォーカスして、Astro での例を中心に解説します。
Next.js などの他のフレームワークでも使い方はほとんど同じなので、参考にしてみてください。

microCMS リッチエディタ用ライブラリとは？

microcms-rich-editor-handler は、以下のような機能を備えています。

画像の最適化
?fm=webp や ?w=幅 といったパラメータを自動的に挿入して、軽量化した画像を配信
シンタックスハイライト
コードブロックにハイライトを簡単に適用できる（Shiki のテーマを設定できるなど）
目次生成
見出しタグ（h1〜h6）を自動的に解析し、目次データを生成

設定はオプションごとに選べるため、「今回はシンタックスハイライトだけ使いたい」「画像最適化だけ導入したい」といった柔軟な運用が可能です。

シンタックスハイライトの実装例 (Astro)

以下では、Astro でシンタックスハイライトを導入する具体的なコード例を紹介します。
microcms-rich-editor-handler が提供する syntaxHighlightingByShikiTransformer を使い、コードブロックを自動的にハイライトしてくれます。

（Astroの場合、専用のシンタックスハイライトは現在のところなく、---で囲まれる間はJavaScript, TypeScriptでそれ以下はHTMLが対象になる。なにかいいハイライトの言語設定はないでしょうか）

[postId].astro

---
import {
  codeBlockFileNameTransformer,
  microCMSRichEditorHandler,
  syntaxHighlightingByShikiTransformer,
} from "microcms-rich-editor-handler";

const { postId } = Astro.params;
const post = await getPostBySlug(postId);
const { html } = await microCMSRichEditorHandler(post.content, {
  transformers: [
    codeBlockFileNameTransformer(), // ファイル名を表示
    syntaxHighlightingByShikiTransformer({
      highlightOptions: {
        html: {
          lang: "html",
          theme: "github-dark",
        },
        typescript: {
          lang: "typescript",
          theme: "github-dark",
        },
      },
      defaultHighlightOptions: {
        lang: "text",
        theme: "vitesse-dark",
      },
    }),
  ],
});
---

<Layout>
  {/* 本文 */}
  <div class="rich-text mt-8" set:html={html} />
</Layout>

ファイル名の表示

microCMSにはコードブロックに対してファイル名を設定できます。

ここではTailwind CSSを使った例ですが、普通のCSSでもOKです。
codeBlockFileNameTransformer を使う場合、ファイル名を表示するための [data-filename] 属性が追加されます。そのスタイルを以下のようにカスタマイズすると、ファイル名がコードブロック上部に表示されるようになります。

global.css

.rich-text pre code {
  @apply bg-transparent; /* 背景色の打ち消し用 */
}

.rich-text div[data-filename] {
  @apply relative;
}

.rich-text [data-filename] {
  @apply relative max-w-xs sm:max-w-screen-sm;
}

.rich-text [data-filename] > span {
  @apply absolute -top-5 left-0 rounded-t-sm border border-[#24292e] bg-[#24292e] px-2 pb-2 pt-1 font-mono text-xs text-white shadow-sm;
}

Transformer 解説

codeBlockFileNameTransformer()

microCMSRichEditorHandler でリッチエディタから返されるコードブロックをパースし、ファイル名などを抽出して [data-filename] 属性として出力してくれます。

syntaxHighlightingByShikiTransformer()

Shiki を使ってコードブロックをハイライトしてくれる Transformer です。
highlightOptions に言語とテーマを指定することで、言語ごとに違うテーマを当てるなどの細かい制御が可能です。

未指定の言語には defaultHighlightOptions が適用されるため、Markdown 内で言語が書かれていないコードブロックも色つきで表示できます。

よくある疑問・トラブルシュート

ファイル名が表示されない / 余白が崩れる
- [data-filename] 用の CSS を正しく設定できているか確認
- Tailwind や SCSS などの環境で何か競合が起きていないかチェック
思った通りのテーマカラーが適用されない
- 指定したテーマ名が正しいかチェック（Shiki が対応しているテーマ名は公式を参照）
- highlightOptions の書き方が間違っていないか確認
サーバー側でビルド時にエラーが出る場合
- Node.js のバージョンや Astro のバージョンとの互換性をチェック

まとめ

以上が、microCMS のリッチエディタ用ライブラリを使って シンタックスハイライト を実装する手順です。

syntaxHighlightingByShikiTransformer() と codeBlockFileNameTransformer() を使えば、テーマやファイル名を自由にカスタマイズできる
言語ごとにテーマを切り替えたり、デフォルトを別テーマにしたりと柔軟に設定可能
Astro でも Next.js でも導入方法はほぼ同じ

きれいなコードブロックがあるだけで、技術記事の可読性はグッと向上 します。ぜひこの記事を参考に、シンタックスハイライトを導入してみてください。

microCMSのリッチエディタ用ライブラリで画像の最適化、目次実装も可能なので以下の記事もぜひ参考にしてください。

画像の最適化について↓

目次実装について↓

最後まで読んでいただきありがとうございました！