Using Markdown and MDX in Next.js – Dynamic Content with React Components and Custom Styling

Introduction

Markdown is a lightweight markup language for writing content that converts to HTML. MDX extends Markdown by allowing you to embed React components directly in your content files.

Installing Dependencies

To enable MDX support in Next.js, install the following packages:

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

Configuring next.config.mjs

In your project root, configure next.config.mjs like this:

import createMDX from '@next/mdx'

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}

const withMDX = createMDX({
  extension: /\.(md|mdx)$/,
})

export default withMDX(nextConfig)

Defining MDX Components

Create an mdx-components.tsx file in your project root:

import type { MDXComponents } from 'mdx/types'

const components: MDXComponents = {}

export function useMDXComponents(): MDXComponents {
  return components
}

This file is required when using MDX with the App Router.

Using File-Based Routing

You can place .mdx files directly in the app directory:

app/mdx-page/page.mdx

Inside the file, use Markdown and React components:

# Welcome

This is **bold** and _italic_ text.

Using Imports

Import MDX files into TypeScript pages:

import Welcome from '@/markdown/welcome.mdx'

export default function Page() {
  return <Welcome />
}

Dynamic Loading with Route Parameters

Load MDX files dynamically based on slug:

export default async function Page({ params }) {
  const { slug } = await params
  const { default: Post } = await import(`@/content/${slug}.mdx`)
  return <Post />
}

export function generateStaticParams() {
  return [{ slug: 'welcome' }, { slug: 'about' }]
}

export const dynamicParams = false

Custom Styling with Components

Override default HTML elements with custom React components:

const components = {
  h1: ({ children }) => (
    <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
  ),
}

Local Component Overrides

Apply custom styles to a specific page:

const overrideComponents = {
  h1: ({ children }) => (
    <h1 style={{ color: 'blue', fontSize: '100px' }}>{children}</h1>
  ),
}

<Welcome components={overrideComponents} />

Shared Layouts

Use shared layouts across MDX pages:

export default function MdxLayout({ children }) {
  return <div style={{ color: 'blue' }}>{children}</div>
}

Using Tailwind Typography

Install @tailwindcss/typography and apply prose classes to your layout:

export default function MdxLayout({ children }) {
  return (
    <div className="prose prose-h1:text-5xl dark:prose-headings:text-white">
      {children}
    </div>
  )
}

Conclusion

Markdown and MDX in Next.js offer a powerful way to combine content and interactivity. With proper configuration, you can build scalable, styled, and dynamic pages that are easy to maintain and delightful to use.