Last updated on

Astro の Markdown でコードに色がつくのは Shiki のおかげ（組み込みと、外で使うとき）

  • Astro
  • Markdown
  • Shiki

このサイトの記事は src/content/blog/ の Markdown を Content Collections から読み、ビルド時に HTML にしています。本文の バッククォート三つで囲んだコードブロック（```js のように言語名を付けたもの）は、ブラウザ上で別ライブラリを読み込んでから色付けするのではなく、サイトをビルドするときにすでに色付きの HTML として埋め込まれる、という動きになります。その着色には Shiki が使われています。

Shiki とは

Shiki（式）は、VS Code と同じ考え方の文法・テーマを使ってソースコードにシンタックスハイライトを付けるためのライブラリです。公式の説明では、VS Code のハイライトエンジンと同系統であること、多くの言語に対応することなどが挙げられています（Shiki のガイド）。

ざっくり言うと、「コードの文字列」と「言語名」「テーマ名」を渡すと、色付きの HTML 文字列（トークンごとに style が付いた span など）を返してくれる、というイメージで足ります。内部がどうパースされているかまで追わなくても、ビルドやサーバー側で一度 HTML を生成しておき、静的に配る用途に向いています。

Astro では Shiki が「最初から」使える

Astro は Shiki と Prism の両方に対応している、とドキュメントに書かれています（Syntax highlighting（構文の色付け））。そのうえで、Markdown や MDX のコードフェンス（```）は、デフォルトで Shiki によってスタイルされる、と説明されています。つまり、別途「ハイライト用の npm パッケージを選んで Astro に載せる」必要はなく、プロジェクト作成時点から Markdown のコードブロックは Shiki 経由で処理される、という位置づけです。

既定のテーマは github-dark で、出力は主に インラインの style になり、余計なクライアント用 JS やスタイルシート一式が必須、という説明も同じページにあります。細かいオプション（テーマの変更、折り返し、ライト／ダークの複数テーマなど）は astro.config の markdown.shikiConfig から渡します。一覧は Markdown の設定 や設定リファレンスの markdown 周りを参照するのが確実です。

Astro 側では、Shiki が付けるクラス名のうち shiki を astro-code に置き換えるなどの調整がドキュメント化されています。Shiki 単体のドキュメントに載っている .shiki 向けの CSS 例を持ってきたときは、.astro-code に読み替える必要がある、と書かれています（上記 Syntax highlighting 内の「Customizing Shiki themes」付近）。

.astro や MDX では、ビルトインの <Code> コンポーネント（Shiki 利用）や、別途インストールする Prism 用の <Prism> も選べます。本記事の主題は Markdown のフェンスなので、ここでは「デフォルトは Shiki」と覚えておけば十分です。

自分のプロジェクトでテーマなどを変える

astro.config.mjs の markdown.shikiConfig で、テーマや折り返しなどを上書きします。

import { defineConfig } from 'astro/config';

export default defineConfig({
	markdown: {
		shikiConfig: {
			theme: 'github-light',
			wrap: true,
		},
	},
});

themes でライト／ダークを分ける、langAlias や transformers を渡す、といった上級の話は Markdown の設定 および Shiki のドキュメント に委ねる形にします。

サイト全体の余白・フォント・背景など、ブロックの「器」は、テーマとは別に 自分の CSS（このプロジェクトでは src/styles/global.css の pre / code など）で整える、という分担になります。

Astro 以外で Shiki を使うには

Astro に限らず、Node や別フレームワーク、独自のビルドスクリプトから Shiki を直接使えます。公式では npm install -D shiki のあと、codeToHtml にコード・言語・テーマを渡して HTML 文字列を得る、という手軽な例が Installation & Usage に載っています。繰り返しハイライトする場合は createHighlighter でインスタンスを作る流れも同ページで説明されています。

ブラウザから CDN 経由で読み込む例もあり、**「Astro を使わない静的サイト」「ドキュメント生成ツール」「ブログのプレビュー用スクリプト」**などでも同じ Shiki を利用できます（詳細は Installation & Usage の CDN の節）。

まとめ

  • このサイトのように Markdown のコードフェンスに色がつくのは、Shiki がビルド時に HTML を生成しているからである。
  • Astro には Shiki が組み込まれており、Markdown／MDX のフェンスは デフォルトで Shiki（既定テーマ github-dark）になる。公式は Syntax highlighting を参照。
  • 見た目やテーマを変えたいときは astro.config の markdown.shikiConfig。詳細は Markdown の設定 を参照。
  • Astro 以外では shiki パッケージを入れて codeToHtml などを呼ぶ。手順は Shiki Installation & Usage を参照。

内部実装（どのプラグインがどの順で動くか）に興味が出たら、そのときに @astrojs/markdown-remark のソースや unified のドキュメントを追うとよいですが、**サイトを書くうえでは「Shiki が組み込まれている」「設定は markdown.shikiConfig」**で十分なことが多いです。