Astro Markdown 応用：ブログをプロ品質に引き上げる 7 つの実践テクニック

Astro でブログを立ち上げ、いざ技術記事を書き始めたとき、こんな壁にぶつかったことはありませんか？コードの特定行だけハイライトしたいのにできない。注意事項を折りたたみ付きのアラートで出したいのに無理。アルゴリズム解説に数式を入れたいけど、やり方がわからない。

私も同じでした。純 Markdown で数本書いたあと、表現の幅の狭さに気づきます。他の技術ブログでは行の強調や差分表示、記事内のインタラクティブな UI があるのに、自分はコードを貼るだけ——そんなギャップを感じていました。

Astro には MDX という「強化版 Markdown」があります。記事の中でコンポーネントや JSX が使えるようになり、できることが一気に広がります。

この記事では、Astro の Markdown/MDX 応用テクニックを 7 つ紹介します。環境構築からコードハイライト、カスタムコンポーネント、数式、フローチャートまで、手順とコード例を揃えました。読み終える頃には、ブログの見え方が「読める」から「プロっぽい」へ近づくはずです。

第 1 部：基本編 — Markdown から MDX へ

なぜ MDX なのか？

Markdown と MDX の違いは、自転車と電動アシスト自転車のようなもの。どちらも進めますが、体験はまったく違います。

純 Markdown はテキスト、コードブロック、画像など静的コンテンツに限られます。注意ボックスを出すなら HTML を直書き。インタラクティブなコンポーネントの埋め込みはほぼ無理です。

MDX は「Markdown + JSX」です。次のことができます。

• コンポーネントの import と利用：.mdx から Astro / React / Vue コンポーネントを読み込める
• JSX 式：{variable} で変数を差し込み、ループや条件分岐も書ける
• 要素のカスタマイズ：標準の <h1> などを自作コンポーネントに置き換えられる

例えば警告ボックス。純 Markdown なら次のように HTML を書きます。

<div class="warning">
  <p>注意：この操作はすべてのデータを削除します！</p>
</div>

MDX ならこう書けます。

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  注意：この操作はすべてのデータを削除します！
</Alert>

違いがわかりますか？ MDX では記事が「コードを書く」より「部品を組み立てる」感覚に近づきます。

5 分で MDX 環境を構築

設定はとても簡単。3 ステップです。

ステップ 1：統合パッケージのインストール

Astro プロジェクトのルートで実行します。

npx astro add mdx

CLI が @astrojs/mdx を入れ、設定を更新します。質問には基本的に Yes で問題ありません。

ステップ 2：設定の確認

astro.config.mjs に次のような記述があるか確認します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

自動追加されなければ手動で足してください。

ステップ 3：MDX が動くかテスト

src/pages/ または src/content/ に test.mdx を作成します。

---
title: MDXテスト
---

# これは MDX のテストです

普通の Markdown テキスト。

export const greeting = "こんにちは";

変数も使えます：{greeting}！

<div style="padding: 1rem; background: #f0f0f0;">
  これは JSX 要素です
</div>

npm run dev でページを開き、変数と JSX が表示されれば成功です。

補足：.md と .mdx の共存

MDX を入れても .md はそのまま動きます。拡張子で処理が切り替わります。

• .md：標準 Markdown
• .mdx：コンポーネントと JSX に対応

普通の記事は .md、コンポーネントが要る記事だけ .mdx、という使い分けで十分です。

第 2 部：コードハイライトの応用テクニック

コードハイライトテーマの設定（Shiki）

Astro はデフォルトで Shiki を使います。テーマは github-dark ですが、ブログの雰囲気に合わせて変えたいことも多いでしょう。

Shiki と Prism、どちらを選ぶ？

私は Shiki を推します。Astro 標準で、100 以上の言語とテーマに対応し、サーバー側レンダリングのため追加 JS が不要です。Prism も悪くありませんが、CSS の読み込みなど設定がやや手間です。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

組み込みテーマの切り替え

astro.config.mjs の markdown に shikiConfig を追加します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // github-dark, nord, monokai, dracula など
    },
  },
});

よく使うテーマの例：

• github-dark / github-light — GitHub 風
• dracula — 紫黒の定番
• nord — 北欧系の落ち着いた配色
• one-dark-pro — VS Code のダークテーマに近い

Shiki テーマ一覧 で好みのものを選べます。

ライト / ダークの二重テーマ

サイトが明暗切り替えに対応しているなら、次のように設定できます。

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

prefers-color-scheme や独自のテーマ切り替えに合わせて、コードのハイライトも切り替わります。

特定行のハイライトとコード注釈

チュートリアルでは「この行が重要」「ここを変更した」を示したい場面が多いです。Shiki Transformers で実現できます。

重要行のハイライト

まず transformers 用に Shiki を入れます。

npm install shiki

設定で transformerNotationHighlight を有効化します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { transformerNotationHighlight } from '@shikijs/transformers';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

コードブロック内で // [!code highlight] と書くと、その行が強調されます。

```javascript
function hello() {
  console.log('普通の行');
  console.log('ここがハイライト'); // [!code highlight]
}
```

差分表示（Diff スタイル）

変更前後の比較には transformerNotationDiff を使います。

import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

使い方：

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}
```

-- の行は削除（赤）、++ の行は追加（緑）として表示されます。コード解説記事で重宝します。

特定部分へのフォーカス

transformerNotationFocus を使うと、指定行以外を薄くできます。

import { transformerNotationFocus } from '@shikijs/transformers';

transformers: [
  transformerNotationFocus(),
],

// [!code focus] の例：

```javascript
function process() {
  console.log('薄くなる行');
  console.log('通常表示'); // [!code focus]
  console.log('薄くなる行');
}
```

Expressive Code へのアップグレード（任意）

Shiki だけでは足りない場合は Expressive Code も検討できます。コミュニティ製の拡張で、次のような機能が揃います。

• コードブロックのタイトル
• ワンクリックコピー
• 行番号
• ターミナル風ウィンドウ
• 並列のコード比較（Side-by-Side）

インストール

npx astro add astro-expressive-code

CLI が設定まで済ませてくれます。以降、コードブロックに機能が付きます。

いつ Expressive Code を使う？

最初は Shiki だけでしたが、読者がコードをコピーしやすい UI が欲しくなり Expressive Code に切り替えました。チュートリアル中心のブログなら体験が良くなります。

コードをたまに載せる程度なら、Shiki + Transformers で十分。依存を増やさなくてよい場面も多いです。

第 3 部：カスタムコンポーネントの埋め込み

MDX でコンポーネントを import して使う

MDX の真骨頂は、記事内でそのままコンポーネントを使えることです。アラート、コード比較、折りたたみなどに向いています。

アラートコンポーネントを作る

src/components/Alert.astro を作成します。

---
interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};
---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

MDX 記事での利用

.mdx で import して使います。

---
title: 私の技術記事
---

import Alert from '@/components/Alert.astro';

# 記事タイトル

本文テキスト。

<Alert type="warning">
  注意：コマンド実行前にバックアップを取ってください！
</Alert>

<Alert type="info">
  ヒント：コンポーネント内でも **Markdown** が使えます。
</Alert>

<Alert> の中でも Markdown（太字やリンクなど）が効くのが MDX の便利なところです。

React / Vue コンポーネント

フレームワークコンポーネントを使うときは client: ディレクティブが必要です。

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load はページ読み込み時にクライアントで動かす指定です。付けないと SSR のみになり、クリックなどの操作は動きません。

コンポーネントの置き場所

記事用コンポーネントは src/components/mdx/ にまとめると管理しやすいです。

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro
│   └── ...その他

Markdown 要素をカスタムコンポーネントにマッピング

少し「黒魔術」に近い機能です。h1 や a、img など標準要素を自作コンポーネントに差し替えられます。

なぜ使う？

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

見出しにアンカーアイコンを付けたい、外部リンクに ↗ を自動で付けたい——毎回手作業は面倒です。マッピングすれば普通の Markdown を書くだけでスタイルが揃います。

実践：カスタム見出し

CustomHeading.astro を作成します。

---
interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;
---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

MDX でマッピング

components オブジェクトを export します。

---
title: 記事タイトル
---

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## これは h2

ホバーすると # アンカーが現れます。

### これは h3

h2 / h3 に共通スタイルが当たります。

実践：外部リンクにアイコン

ExternalLink.astro：

---
interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');
---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

マッピング例：

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[内部リンク](/about)
[外部リンク](https://example.com) ← 自動で ↗ が付く

グローバルマッピング（上級）

全 MDX で同じマッピングにしたい場合は astro.config.mjs 側のカスタム MDX プラグインも可能ですが、手間が増えるので、私は記事ごとの components export で足りています。

第 4 部：数式と図表の統合

KaTeX で数式を表示

アルゴリズムやデータサイエンスの記事では数式が欠かせません。KaTeX は MathJax より高速で、SSR とも相性が良いです。

インストール

npm install remark-math rehype-katex katex

• remark-math：LaTeX 構文の解析
• rehype-katex：HTML へのレンダリング
• katex：コアライブラリ

Astro の設定

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

KaTeX の CSS

レイアウト（例：src/layouts/MarkdownLayout.astro）の <head> に追加します。

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

記事での記法

インライン（$...$）：

質量エネルギー等価：$E = mc^2$

二次方程式の解：$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

ブロック（$$...$$）：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

よくある不具合

表示されないときは次を確認してください。

1. KaTeX CSS が読み込まれているか（DevTools の Network）
2. rehype-katex のバージョン互換（6.x に下げる例もある）
3. 式の構文が KaTeX 対応一覧 に含まれるか

Mermaid でフローチャートと図表

Mermaid はコードからフローチャート、シーケンス図、ガント図などを描けます。

統合方式の比較

私は rehype-mermaid を推します。ビルド時に静的 SVG になり、SEO と表示速度に有利です。

rehype-mermaid の導入

npm install rehype-mermaid

設定：

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

strategy: 'img-svg' は SVG 画像として出力する安定した方式です。

記事での記述

mermaid 言語のコードブロックを使います。

フローチャート例：

```mermaid
graph TD
    A[開始] --> B{MDX導入済み？}
    B -->|はい| C[ハイライト設定]
    B -->|いいえ| D[MDXをインストール]
    D --> C
    C --> E[完了]
```

シーケンス図例：

```mermaid
sequenceDiagram
    ユーザー->>ブラウザ: ページアクセス
    ブラウザ->>サーバー: HTML 要求
    サーバー->>ブラウザ: レンダリング済み HTML
    ブラウザ->>ユーザー: 表示
```

npm run build 時に SVG が生成され、ページは静的画像として配信されます。クライアント JS は不要です。

注意

ビルドで Puppeteer 関連のエラーが出る場合は playwright を入れるか、astro-diagram など別方式を試してください。

npm install -D playwright

第 5 部：応用テクニックとベストプラクティス

Content Collections と MDX の相性

ブログ記事は Astro の Content Collections で管理するのがおすすめです。src/content/ に置くと frontmatter の検証と型安全な取得 API が使えます。

Content Collections とは

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

記事を src/content/ に置き、frontmatter をスキーマで検証し、型付き API で読み出す仕組みです。

設定例

src/content/config.ts：

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

MDX での利用

frontmatter は自動検証されます。

---
title: Astro MDX 応用チュートリアル
description: MDX の上級テクニックを学ぶ
pubDate: 2025-12-02
tags: [Astro, MDX, チュートリアル]
---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  公開日：{frontmatter.pubDate.toLocaleDateString()}
</Alert>

目次の自動生成

getHeadings() で見出し一覧を取り、目次にできます。

---
import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();
---

<aside>
  <h2>目次</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

長文では読者が章へ飛びやすくなります。

パフォーマンスとよくある落とし穴

MDX は強力ですが、使い方を誤るとサイトが重くなります。

クライアントコンポーネントの使いすぎに注意

React / Vue を MDX に入れるときは client:* が必要です。付けないとインタラクションは動きません。一方、client:load の乱用は JS 量を増やし、表示を遅くします。

目安：

• 静的 UI は Astro コンポーネント（Alert、Callout など）
• インタラクションが要るときは client:visible や client:idle を検討
• どうしても必要なときだけ client:load

画像の最適化

<img> の代わりに Astro の Image を使います。

---
title: 私の記事
---

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="カバー画像" width={800} height={600} />

圧縮、WebP 生成、遅延読み込みなどが自動で効きます。

MDX の optimize オプション

MDX が多くてビルドが遅い場合：

export default defineConfig({
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

内部の rehype 最適化でビルドが速くなることがあります。HTML 構造が変わる可能性があるので、導入前にプレビューで確認してください。

よくあるエラー

まとめ

要点を整理します。

7 つのテクニックのおさらい：

1. MDX 環境 — コマンド一発、5 分で開始
2. ハイライトテーマ — Shiki で好みの見た目に
3. 行の強調・差分 — Transformers で注釈
4. カスタムコンポーネント — Alert からインタラクティブ Demo まで
5. 要素マッピング — 見出しやリンクを一括カスタム
6. 数式 — KaTeX でアルゴリズム解説を強化
7. 図表 — Mermaid をコードで描画、SSR で SEO に有利

学習の進め方

一度に全部やる必要はありません。

• 第 1 段階：MDX を入れ、簡単なコンポーネントを 1 つ試す
• 第 2 段階：コードが多いならハイライトを整える
• 第 3 段階：アルゴリズムや設計記事なら KaTeX と Mermaid
• 第 4 段階：慣れたら要素マッピングなど応用へ

チェックリスト

• MDX が正しくレンダリングされる
• コードブロックにハイライトがある
• カスタムコンポーネントが表示される
• 数式が正しい（設定した場合）
• Mermaid 図が生成される（設定した場合）
• ビルド時間が許容範囲

次の一歩

• Astro Integrations でプラグインを探す
• コミュニティの MDX コンポーネント集を参考にする
• Astro の View Transitions でページ遷移を滑らかにする

気になる機能から 1 つ試してみてください。つまずいても公式ドキュメントとコミュニティで大抵解決できます。

最後に——ツールは表現を助けるもので、読者を引きつけるのは内容と経験です。Astro ブログがますます良くなることを願っています。