How to add MDX support in Next.js project

What is MDX?

Markdown is a simple markup language used to format text, it converts plain text to structurally valid HTML. It's used for content areas in CMSs and blog posts for static websites.

MDX is superset of markdown, allowing you to add JSX components directly in the markdown files. This means that you can use React components, import other components, and even write inline JSX in your Markdown files.

Why use MDX?

MDX is a great way to write interactive documentation, blog posts, and other content that requires more than just plain text. By using MDX, you can easily embed interactive components, code snippets, and other dynamic content in your Markdown files.

How to use MDX in Next.js?

So first we need to install few packages @next/mdx, @mdx-js/loader, @mdx-js/react, @types/mdx

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

Update your next.config.ts to include page extensions and additional plugins: remark-gfm for GFM (GitHub Flavored Markdown) like autolink literals, footnotes, strikethrough, tables, tasklists, and rehype-slug that turns markdown into HTML

import createMDX from "@next/mdx";

/** @type {import('next').NextConfig} */
const nextConfig = {
	experimental: {
		viewTransition: true,
	},
	pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
};

const withMDX = createMDX({
	options: {
		remarkPlugins: [
			"remark-gfm",
		],
		rehypePlugins: [
			"rehype-slug",
		],
	},
});

export default withMDX(nextConfig);

Then you need to create a mdx-components.tsx file at the root of your application:

import type { MDXComponents } from 'mdx/types'
import { components } from './components/mdx'


export function useMDXComponents(): MDXComponents {
  return components
}

Example components/mdx.tsx file for components rendering headings, links etc

import Link from "next/link";
import { MDXRemote } from "next-mdx-remote/rsc";
import React, { type ReactNode } from "react";
import remarkGfm from "remark-gfm";
import { highlight } from "sugar-high";

function CustomLink(props: any) {
	const href = props.href;

	if (href.startsWith("/")) {
		return (
			<Link href={href} {...props}>
				{props.children}
			</Link>
		);
	}

	if (href.startsWith("#")) {
		return <a {...props} />;
	}

	return <a target="_blank" rel="noopener noreferrer" {...props} />;
}

function Code({ children, ...props }: { children: any }) {
	const codeHTML = highlight(children);
	return <code dangerouslySetInnerHTML={{ __html: codeHTML }} {...props} />;
}

function slugify(str: string) {
	return str
		.toString()
		.toLowerCase()
		.trim() // Remove whitespace from both ends of a string
		.replace(/\s+/g, "-") // Replace spaces with -
		.replace(/&/g, "-and-") // Replace & with 'and'
		.replace(/[^\w-]+/g, "") // Remove all non-word characters except for -
		.replace(/--+/g, "-"); // Replace multiple - with single -
}

function createHeading(level: number) {
	const Heading = ({ children }: { children: any }) => {
		const slug = slugify(children);
		return React.createElement(
			`h${level}`,
			{
				id: slug,
				className: "scroll-mt-20",
			},
			[
				React.createElement(
					"a",
					{
						href: `#${slug}`,
						key: `link-${slug}`,
						className: "no-underline",
					},
					children,
				),
			],
		);
	};

	Heading.displayName = `Heading${level}`;

	return Heading;
}

export const components = {
	h1: createHeading(1),
	h2: createHeading(2),
	h3: createHeading(3),
	h4: createHeading(4),
	h5: createHeading(5),
	h6: createHeading(6),
	a: CustomLink,
	code: Code
};

This is all that is required to support mdx files in Nextjs.

To use mdx as component we can the MDXRemote plugin to create CustomMDX component in components/mdx.tsx:

import { MDXRemote } from 'next-mdx-remote-client/rsc'

export function CustomMDX(props: any) {
	return (
		<MDXRemote
			{...props}
			components={{ ...components, ...(props.components || {}) }}
			options={{
				parseFrontmatter: true,
				mdxOptions: {
					remarkPlugins: [remarkGfm],
				},
			}}
		/>
	);
}

The component property can be extended by any React component like one containing some animation. You can also use HTML

import { GradualSpacing } from "@/components/animations/gradual-spacing";
<div className="text-4xl font-bold bg-white px-10">
	<GradualSpacing text="MDX components" />
</div>

Conclusion

MDX makes a great way to add any components to your Markdown files just as it was an JSX file. Helps builds interactive documentation, static generated content and web application. With Next.js has now became straightforward and easy to implement.