MDXチートシート
2025年5月14日
L Azlan Rafar
ソフトウェアエンジニア
このリファレンスの目的
このドキュメントは、本プロジェクトで使用しているMDX設定に関する情報を一か所にまとめるために作成しました。コンテンツ量の多いサイトを構築していると、カスタムコンポーネントの書き方やコードブロックに必要なアノテーションを忘れがちです。このチートシートは、既存の設定を使いたい人や理解したい人がすぐに参照できるクイックリファレンスです。
なぜMDXなのか
MDXを採用したのは、単なる静的テキスト以上のものが必要だったからです。標準的なMarkdownの読みやすさを損なわずに、技術ドキュメントの中にインタラクティブな要素やライブプレビュー、リッチメディアを織り交ぜたいと考えました。この2つの世界を組み合わせることで、開発者にもライターにも自然に使える強力な仕組みが実現します。
基本的なMarkdown記法
MDXは、標準的なMarkdownの機能をすべてそのままサポートしています。より複雑なコンポーネントを追加する前に、これらを使って素早く考えを整理できます。
タイポグラフィとリスト
シンプルな記号で、見出し、リスト、基本的なテキスト装飾を作成できます。
- 太字:強調に使用
- 斜体:さりげない強調に使用
Inline code:変数や短いコード片に使用
重要な考えやアドバイスを目立たせるための引用ブロックもサポートしています。
Markdownは土台であり、MDXはその上によりインタラクティブなものを築くための骨組みです。
フロントマターによるメタデータ管理
本プロジェクトのMDXファイルには、必ず先頭にYAMLのフロントマターブロックが必要です。ビルドシステムはこれを使って、ページタイトル、説明文、サムネイルを生成します。
このメタデータは、SEOや、ブログ一覧とナビゲーションリンクの自動生成に欠かせません。
Rehype Pretty Codeによるシンタックスハイライト
コードブロックを読みやすくするために、rehype-pretty-codeというプラグインを使用しています。このツールはビルド時にシンタックスハイライトを処理するため、ユーザーは色付きのテキストを表示するためだけに大きなライブラリをダウンロードする必要がありません。
ハイライト機能
このプラグインは、通常の色付けにとどまらない便利なアノテーションをいくつかサポートしています。
- 行のハイライト:
// [!code highlight]を使うと、特定の行を目立たせられます。 - 差分表示:
// [!code ++]または// [!code --]を使うと、コードの変更点を表示できます。 - 単語のハイライト:
// [!code word:X]を使うと、特定の単語をすべてハイライトできます。
コードブロックの例
カスタムコンポーネント
MDXを使う大きな理由の一つは、Reactコンポーネントをコンテンツに直接埋め込めることです。ドキュメント用の再利用可能なUIパターンを作るのに役立ちます。
Alertコンポーネント
特定の情報を目立たせるには、Alertコンポーネントを使用できます。
これらのコンポーネントは、本文から目立たせたいメモ、警告、補足説明に最適です。
リッチメディアの埋め込み
シンプルなテキストやコードだけでなく、MDXではiframeやカスタムウィジェットを使ってサードパーティのコンテンツを組み込むこともできます。
音楽とオーディオ
SpotifyやApple Musicの音楽プレーヤーを埋め込んで、記事にBGMを添えたり、特定の曲をシェアしたりできます。
Spotifyのトラック
Spotifyのアルバム
動画コンテンツ
YouTube動画はシンプルなiframeで埋め込めます。どの画面サイズでも動画が正しく拡大縮小されるよう、アスペクト比16:9の使用をおすすめします。
Next.jsとの技術的な統合
内部では、本プロジェクトは**@next/mdx**を使ってビルド時にMDXファイルを処理しています。コンテンツをコンパイル済みのReactコンポーネントのように扱うため、記事の取得、日付順の並べ替え、フロントマターの自動検証が可能です。
この構成のメリット
- 型安全性:すべての記事は
lib/posts.tsのスキーマに基づいて検証されます。 - パフォーマンス:コンテンツはビルド時に処理・最適化されます。
- 柔軟性:rehypeやremarkのプラグインを簡単に追加して、MDXシステムの機能を拡張できます。
おわりに
このチートシートは、プロジェクトの成長に合わせて更新していきます。執筆中に特定の機能の実装方法に迷ったら、まずここを確認してください。これらのパターンに従うことで、サイト全体の一貫性とパフォーマンスを保てます。
画像:Camila Q. Franco