📘 Next.js에서 MDX 사용 가이드

📘 Next.js에서 MDX 사용 가이드

MDX는 Markdown과 JSX를 결합하여 정적인 콘텐츠와 동적인 컴포넌트를 함께 사용할 수 있는 강력한 포맷입니다.
Next.js App Router에서도 쉽게 MDX를 통합하고 사용할 수 있도록 구성할 수 있습니다.

---

✅ 1. MDX란?

MDX(Markdown + JSX)는 일반적인 Markdown 파일 안에 React 컴포넌트를 직접 삽입할 수 있는 문서 포맷입니다.
이를 통해 다음과 같은 작업이 가능합니다:

• 블로그에서 <VideoPlayer />, <CodeBlock /> 삽입
• 기술문서에 <Tabs />, <Alert />와 같은 인터랙티브 컴포넌트 사용
• Markdown 기반 포트폴리오 페이지 구축

---

✅ 2. 패키지 설치

다음 명령어를 통해 MDX 통합에 필요한 패키지를 설치합니다:

npm install @next/mdx @mdx-js/loader @mdx-js/react

또는

yarn add @next/mdx @mdx-js/loader @mdx-js/react

---

✅ 3. next.config.js 설정

MDX 파일을 페이지로 인식하기 위해 next.config.js에 아래 설정을 추가합니다.

// next.config.js
const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
});

module.exports = withMDX({
  pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
});

.mdx 확장자를 페이지로 인식하려면 pageExtensions를 반드시 설정해야 합니다.

---

✅ 4. MDX 파일 작성 및 사용

# 소개합니다

Next.js에서는 **MDX**를 사용하여 다음처럼 컴포넌트를 삽입할 수 있습니다.

<CustomButton>클릭하세요!</CustomButton>

해당 파일을 app/docs/page.mdx에 위치시켜 페이지처럼 사용하거나, 동적으로 import할 수 있습니다.

---

✅ 5. 커스텀 컴포넌트 연결

반응형

MDX 내부에서 사용할 컴포넌트를 지정할 수 있습니다.

// mdx-components.tsx
import CustomButton from './components/CustomButton';

export const components = {
  CustomButton,
};

// app/docs/page.tsx
'use client';
import { MDXProvider } from '@mdx-js/react';
import Content from './page.mdx';
import { components } from '../../mdx-components';

export default function DocsPage() {
  return (
    <MDXProvider components={components}>
      <Content />
    </MDXProvider>
  );
}

---

✅ 6. next-mdx-remote를 통한 동적 로딩

외부 CMS나 파일시스템에서 MDX 콘텐츠를 불러오려면 next-mdx-remote를 사용할 수 있습니다.

설치

npm install next-mdx-remote

예시

// app/blog/[slug]/page.tsx
import fs from 'fs';
import path from 'path';
import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';
import { components } from '../../../mdx-components';

export async function generateStaticParams() {
  return [{ slug: 'hello' }];
}

export default async function BlogPage({ params }: { params: { slug: string } }) {
  const file = fs.readFileSync(path.join('content', `${params.slug}.mdx`), 'utf-8');
  const mdxSource = await serialize(file);
  return <MDXRemote {...mdxSource} components={components} />;
}

---

✅ 7. 코드 하이라이팅 추가 (옵션)

코드 블록 하이라이팅을 원한다면 rehype-highlight 플러그인을 사용할 수 있습니다.

설치

npm install rehype-highlight

설정

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    rehypePlugins: [require('rehype-highlight')],
  },
});

---

✅ 8. App Router에서 MDX 사용 팁

항목 설명

App Router 지원 여부	✅ .mdx 페이지 직접 사용 가능
클라이언트 컴포넌트	<Content />는 반드시 'use client' 상단 선언
레이아웃 공유	.mdx는 일반 tsx와 동일하게 layout.tsx와 연동됨
컴포넌트 마크업 제한	React 전용 기능 (useState, useEffect)은 .tsx에서만

---

✅ 요약

기능 방법

MDX 사용	@next/mdx 설정 및 .mdx 파일 생성
컴포넌트 연결	@mdx-js/react의 MDXProvider 사용
코드 하이라이팅	rehype-highlight 플러그인 설치 및 적용
외부 콘텐츠 렌더링	next-mdx-remote 활용 (serialize, MDXRemote)
App Router 호환	.mdx 페이지 직접 라우팅 가능

---

 

Next.js, MDX, Markdown, JSX, 정적 페이지, 블로그, 기술문서, 컴포넌트 삽입, next-mdx-remote, rehype-highlight, App Router, SEO 최적화