07. AstroでMarkdownとMDXを使いこなす | Cloud AI エンジニア入門ガイド

この章の全体像として、置き場所、処理パイプライン、ハイライト、MDXの4つを番号順に並べ、記事の書き方と拡張の仕方を選べるようになることを示した図

シリーズ目次／前章: 06. Astro コンテンツコレクションで記事を管理する／次章: 08. AstroのアイランドアーキテクチャとUIフレームワーク

Open Table of contents

この章のねらい
Markdownファイルの基本
Markdownの処理パイプライン
シンタックスハイライト
MDX：Markdownにコンポーネントを混ぜる
- MarkdownとMDXの使い分け
要点
参考資料

この章のねらい

Astroでコンテンツを書く主役はMarkdownです。前章ではコレクションによる管理を見ましたが、ここではMarkdownそのものがどう処理され、どこまで拡張できるかを見ます。

Astro 7でMarkdownの処理エンジンが入れ替わったので、ネット上の既存の情報と食い違う場面が出てきます。その差も押さえておきます。

Markdownファイルの基本

Markdownファイルの先頭には、--- で囲んだフロントマターを書けます。ここにタイトルや公開日などのメタデータを記述します。

---
title: "はじめての記事"
author: "編集部"
pubDate: 2026-08-02
tags: ["入門", "Astro"]
---

## 見出し

本文です。**強調**や[リンク](https://example.com)も使えます。

フロントマターはYAML形式で書きます（TOMLも利用できます）。本文はそのままHTMLに変換されます。

Markdownを使う2つの方法

扱い方は2通りです。

方法	置き場所	特徴
ページとして直接使う	`src/pages/`	ファイルがそのままURLになる。手軽
コンテンツコレクションで管理する	`src/content/` など	スキーマ検証と型が効く。一覧・詳細を作りやすい

src/pages/about.md を置けば /about として公開されます。固定ページが数枚だけならこれで十分です。

一方、記事のように件数が増えて一覧ページも必要になるなら、06. Astro コンテンツコレクションで記事を管理するの方法を選びます。迷ったらコレクションと考えて構いません。

2つの方法を並べると、次のようになります。

src/pagesに置いてファイルをそのままページにする方法と、src/contentに置いてコンテンツコレクションで管理する方法を、置き場所・得られるもの・向いている場面で比較した図

レイアウトを当てる

ページとして直接使う場合は、フロントマターの layout にレイアウトのパスを書きます。

---
layout: ../layouts/BaseLayout.astro
title: "このサイトについて"
---

レイアウト側では Astro.props.frontmatter からメタデータを参照できます。

複数ファイルをまとめて読む

コレクションを使わずに複数のMarkdownを扱いたいときは、Viteの import.meta.glob() が使えます。

---
const posts = Object.values(
  import.meta.glob("../posts/*.md", { eager: true })
);
---

<ul>
  {posts.map(post => (
    <li><a href={post.url}>{post.frontmatter.title}</a></li>
  ))}
</ul>

手軽ですが、フロントマターの検証は効きません。小規模なうちだけの選択肢です。

Markdownの処理パイプライン

Markdownがどのように処理されるかを図にすると、次のようになります。

Markdownファイルがフロントマター分離、プロセッサによる解析、シンタックスハイライトを経てHTMLになり、レイアウトへ差し込まれる流れを示した図

真ん中のプロセッサは差し替えられます。

既定のプロセッサ（Astro 7）

Astro 7では、既定のMarkdownプロセッサがAstro独自の実装（@astrojs/markdown-satteri パッケージの satteri()）に変更されました。速度を重視して作られており、GitHub Flavored MarkdownとSmartyPantsが適用されます。

用語: GitHub Flavored Markdown（GFM）は、表・打ち消し線・タスクリストなどを追加したMarkdownの方言です。SmartyPantsは、引用符やハイフンを見栄えのよい記号に自動変換する処理を指します。

明示的に設定する場合は次のように書きます。

// astro.config.mjs
import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";

export default defineConfig({
  markdown: {
    processor: satteri({
      features: { gfm: false },
    }),
  },
});

remark / rehypeを使いたい場合

Markdown界隈には、remark（Markdownを操作する）とrehype（HTMLを操作する）という広く使われたプラグイン群があります。目次を自動生成する remark-toc、絵文字にアクセシブルなラベルを付ける rehype-accessible-emojis など、資産が豊富です。

これらを使いたい場合は、unified プロセッサへ切り替えます。

// astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import remarkToc from "remark-toc";
import rehypeCallouts from "rehype-callouts";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [[remarkToc, { heading: "目次" }]],
      rehypePlugins: [rehypeCallouts],
    }),
  },
});

プラグインにオプションを渡すときは、[プラグイン, オプション] の配列形式にします。

Astro 6以前から移行する場合、remarkPlugins / rehypePlugins をトップレベルに書いていた設定は、この processor: unified({ ... }) の形へ書き換えてください。プラグインを使っているプロジェクトのアップグレードは、まずここで転びます。

プロセッサの選び方

状況	選択
標準的なMarkdownで足りる	既定のまま（設定不要）
ビルド速度を最優先したい	既定のまま
remark / rehypeのプラグインが必要	`unified()` に切り替える
既存プロジェクトを移行する	まず `unified()` で動作を揃え、必要に応じて検討する

remarkやrehypeのプラグインが必要かどうかで分岐し、不要なら既定のプロセッサのまま、必要ならunifiedへ切り替えるという判断の流れと、移行時の注意点を示した図

シンタックスハイライト

コードブロックの色付けは、既定でShiki（シキ）が担当します。設定値の既定は { type: "shiki", excludeLangs: ["math"] } です。

用語: Shikiは、エディタと同じ配色定義を使ってコードを色分けするライブラリです。ビルド時に色付けを済ませるため、閲覧者側でJavaScriptを実行する必要がありません。

テーマは markdown.shikiConfig で変更できます。

export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: {
        light: "github-light",
        dark: "github-dark",
      },
      wrap: false,
    },
  },
});

themes にライト用・ダーク用を両方指定しておくと、配色の切り替えに対応できます。

Markdown側では、コードフェンスに言語名を書くだけです。

```javascript
const message = "こんにちは";
console.log(message);
```

MDX：Markdownにコンポーネントを混ぜる

MDXは、Markdownの中にコンポーネントやJSX式を書ける形式です。Astroでは公式インテグレーションで有効化します。

npx astro add mdx

導入すると、.mdx ファイルが使えるようになります。

---
title: "料金プランの比較"
---

import PriceTable from "../components/PriceTable.astro";
import Alert from "../components/Alert.jsx";

## 現在のプラン

以下の表をご覧ください。

<PriceTable plan="standard" />

<Alert client:visible>
  キャンペーンは今月末までです。
</Alert>

通常のMarkdownも、これまでどおり書けます。

Markdownの読みやすさを保ったまま、必要な箇所にだけ動的な部品を差し込めるのが利点です。

同じ内容を .md と .mdx で書き比べると、増える部分がはっきりします。

拡張子mdのファイルは見出しや本文などのテキストだけを書けるのに対し、mdxのファイルは同じテキストに加えてコンポーネントの取り込みと配置ができることを、ファイルの中身を並べて比較した図

MarkdownとMDXの使い分け

観点	Markdown（`.md`）	MDX（`.mdx`）
書き味	純粋なテキスト。誰でも編集できる	JavaScriptの知識がやや必要
コンポーネント	使えない	使える
処理速度	速い	変換の手間が増える
向いている用途	記事、ドキュメント	製品ページ、対話的な解説

Markdownで書けるならMarkdownで書いてください。コンポーネントが必要になったファイルだけ .mdx にする。これがいちばん散らかりません。

なお、MDXの設定は既存のMarkdown設定を引き継ぎます。引き継ぎ方を制御したい場合は、MDXインテグレーションの extendMarkdownConfig オプションを使います。

要点

Markdownは「ページとして直接置く」方法と「コレクションで管理する」方法がある。件数が増えるなら後者を選ぶ。
Astro 7では既定のMarkdownプロセッサがAstro独自の実装に変わり、速度が向上した。
remark / rehypeのプラグインを使うには processor: unified({ ... }) へ切り替える。移行時の主な確認点である。
コードのシンタックスハイライトはShikiがビルド時に処理し、閲覧者側のJavaScriptを必要としない。
MDXはMarkdownにコンポーネントを混ぜられる。必要なファイルだけMDXにするのがよい。

参考資料

シリーズ目次／前章: 06. Astro コンテンツコレクションで記事を管理する／次章: 08. AstroのアイランドアーキテクチャとUIフレームワーク