markdown

はじめに (対象読者・この記事でわかること)

この記事は、Astroでサイトを構築しており TailwindCSS と MDX を既に導入しているフロントエンド開発者を対象としています。
MDX の中に埋め込まれた React コンポーネントや Tailwind のユーティリティは便利ですが、単純な Markdown のみを扱いたいシーンも多くあります。本記事を読むことで、Astro プロジェクト内で特定のページやディレクトリを「純粋な Markdown 表示」に切り替える設定方法と、Tailwind のスタイルをそのまま活かすテクニックが理解でき、余計なビルドコストや不要な JavaScript の出力を抑えることができるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。
- Astro の基本的なプロジェクト構成と astro.config.mjs の書き方
- TailwindCSS のインストールと tailwind.config.cjs の設定
- MDX を Astro で有効化するためのプラグイン (@astrojs/mdx) の使い方

Astro と Tailwind で「Markdown だけ」ページを作る背景

Astro は「コンポーネント駆動」でも「ページ単位のレンダリング」でも自由度が高く、MDX を利用すると Markdown に React コンポーネントを混在させられる点が魅力です。一方で、ブログ記事やドキュメントページなど、純粋にテキストだけを表示したいケースでは、余計な JavaScript がバンドルされてしまうとページサイズが肥大化し、パフォーマンス低下につながります。

そこで、本稿では次の 3 つのポイントに絞って実装手順を示します。

  1. ページ単位で MDX と純粋 Markdown を切り替える
    - src/pages 配下に拡張子 .md と .mdx を混在させ、Astro が自動で適切なレンダラを選択する仕組みを確認します。
  2. Tailwind のユーティリティクラスを Markdown に適用
    - グローバルに適用するスタイルと、prose（Tailwind Typography） を併用し、Markdown の見出し・リスト・テーブルに一貫したデザインを付与します。
  3. 不要な JavaScript 出力を抑制
    - client:only や client:idle などの指示子を用いず、純粋な静的 HTML と CSS のみで完結させる設定例を紹介します。

これらを実装すれば、MDX の柔軟さはそのまま残しつつ、Markdown 専用ページは完全に静的 な形で提供でき、ユーザー体験と開発効率の両立が可能になります。

具体的な手順や実装方法

以下では、実際にプロジェクトをクローンし、手順に沿って設定を追加していく流れを解説します。コード例はすべて src/pages 配下に配置する想定です。

ステップ1 ― プロジェクトの基本構成を確認

まずは既存の Astro プロジェクトが以下のようになっていることを確認してください。

my-astro/
├─ src/
│  ├─ pages/
│  │  ├─ index.astro
│  │  ├─ blog/
│  │  │  ├─ hello.mdx
│  │  │  └─ pure.md   ← ここに作成する Markdown ファイル
│  ├─ components/
│  └─ layouts/
├─ astro.config.mjs
├─ tailwind.config.cjs
└─ package.json

astro.config.mjs では MDX プラグインが有効化されていることを確認します。

Js

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

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

このままだと .mdx と同様に .md も自動で Astro の Markdown レンダラに委譲され、Tailwind のクラスはグローバル CSS として適用されます。

ステップ2 ― Tailwind Typography を導入

Markdown のデザインを整えるために、Tailwind の公式プラグイン @tailwindcss/typography（通称 prose） を導入します。

Bash

npm i -D @tailwindcss/typography

tailwind.config.cjs にプラグインを追加し、デフォルトの prose スタイルをカスタマイズします。

Js

// tailwind.config.cjs
module.exports = {
  content: ['./src/**/*.{astro,html,js,ts,jsx,tsx,md,mdx}'],
  theme: {
    extend: {
      typography: (theme) => ({
        DEFAULT: {
          css: {
            '--tw-prose-body': theme('colors.gray.800'),
            '--tw-prose-headings': theme('colors.gray.900'),
            '--tw-prose-links': theme('colors.indigo.600'),
            // ここに好きなカラーカスタマイズを書けます
          },
        },
      }),
    },
  },
  plugins: [require('@tailwindcss/typography')],
};

設定が完了すると、prose クラスを付与した要素は自動で美しい typographic スタイルが適用されます。

ステップ3 ― Markdown ページを作成し Tailwind を適用

src/pages/blog/pure.md を新規作成し、以下のように書きます。

Markdown

---
title: "Tailwind だけで描くシンプルな Markdown"
date: 2025-08-09
layout: ../layouts/BlogPost.astro
---

# はじめに

このページは **MDX** ではなく **純粋な Markdown** として書かれています。  
Tailwind の `prose` クラスを使うだけで、見出しやリスト、テーブルが自動的に整形されます。

## 見出しとリスト

- 箇条書きは自動でインデントされます  
- **太字**や *斜体* も自然に表示

## テーブル例

| 名前 | 年齢 | 好きな言語 |
|------|------|------------|
| Alice | 28 | JavaScript |
| Bob   | 34 | TypeScript |

> 引用ブロックも `prose` により見やすくなります。

ポイントは layout フロントマターで Astro のレイアウトコンポーネントを指定している点です。次にレイアウト側で prose クラスを包みます。

Astro

---
// src/layouts/BlogPost.astro
const { title } = Astro.props;
---
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
    <link rel="stylesheet" href="/src/styles/global.css" />
  </head>
  <body class="bg-gray-50 text-gray-900">
    <article class="prose mx-auto py-8">
      <slot />
    </article>
  </body>
</html>

これだけで、Markdown の HTML が prose によってスタイリングされ、余計な JavaScript は一切出力されません。

ステップ4 ― ビルド結果を確認

Bash

npm run build
npm run preview

/blog/pure/ にアクセスすると、ページは 静的 HTML + CSS のみでレンダリングされていることが開発者ツールで確認できます。<script> タグが一切無いことがポイントです。

ハマった点やエラー解決

発生した問題 原因 解決策
Tailwind の prose が効かない tailwind.config.cjs の content に .md が抜けていた content: ['./src/**/*.{astro,html,js,ts,jsx,tsx,md,mdx}'] を追加
MDX と Markdown が同一ディレクトリにあるとビルドが遅くなる Astro が全ファイルを走査し直すため src/pages/blog を分割し、mdx 用と md 用にサブディレクトリを作成
文字列中の --- が Frontmatter と判定される Markdown 本文で横線を使用した --- の代わりに *** か HTML の <hr> を使用

解決策のまとめ

  • tailwind.config.cjs の content に すべての拡張子 を必ず列挙
  • レイアウトコンポーネントで prose をラップし、Tailwind のユーティリティを再利用
  • 不要な JavaScript を排除するために、Markdown ページは コンポーネント化しない（.md ファイルだけで完結）

まとめ

本記事では、Astro + TailwindCSS + MDX 環境下で、純粋な Markdown ページを作成し、Tailwind の prose スタイルで美しく表示させる手順を解説しました。

  • tailwind.config.cjs に @tailwindcss/typography を組み込み、prose クラスで Markdown を自動整形
  • .md ファイルにフロントマターでレイアウトを指定し、JS の出力を抑制
  • ビルド時に発生しやすい content 設定ミスや Frontmatter 衝突を回避するポイントを提示

この方法を採用すれば、コンテンツは軽量かつ高速に配信でき、開発者は MDX の拡張性と Markdown のシンプルさを両立させたサイト設計が可能になります。次回は、MDX と Markdown を同一ページでハイブリッドに扱うテクニックや、astro:page ディレクティブを使った動的切り替えについて書く予定です。

参考資料