MDX in Next.js 16 — Frontmatter Parsing Error Broke 200 Blog Pages at Build Time

MDX combines Markdown with JSX, letting you write content in Markdown while embedding React components — charts, interactive demos, custom callouts — directly in your blog posts. Next.js supports MDX through the @next/mdx package, which compiles MDX files into React components at build time.

This compilation-at-build-time approach is fast — there is no runtime parsing overhead. But it introduces a catch: any MDX file with invalid frontmatter, syntax errors, or broken JSX imports will fail the entire build. In a production incident, a single YAML frontmatter parsing error — a missing space in title:"Post" instead of title: "Post" — caused the build to fail silently, and 200 blog pages didn't make it to production.

This article covers: configuring @next/mdx with App Router, frontmatter validation strategies, draft mode integration with headless CMS previews (including the critical gotcha that draft mode works only with on-demand ISR, not static export), remark and rehype plugin development, production patterns for large MDX collections, and how to recover when your build fails because one file has bad YAML.

By the end, you will have a production-grade MDX pipeline that validates frontmatter at build time, provides draft previews for editors, and catches syntax errors before they abort your deploy.

@next/mdx Setup — The Right Way With App Router

Setting up MDX in Next.js looks simple in the docs: install @next/mdx, configure it in next.config.ts, add MDX files. The reality: there are three different configuration approaches and only one works correctly with the App Router.

For the Pages Router, @next/mdx extends the Webpack config to compile MDX files into page components. For the App Router, the recommended approach is @next/mdx-remote (or the newer next-mdx-remote-client) which compiles MDX at request time or build time via a loader function. The key difference: @next/mdx with App Router requires the experimental.mdxRs flag (Rust-based MDX compiler) for optimal performance.

The configuration: install @next/mdx, @mdx-js/mdx, and @mdx-js/react. In next.config.ts, add withMDX wrapper. For frontmatter, use gray-matter (or front-matter) to parse YAML separately from MDX compilation — @next/mdx does not parse frontmatter into props automatically in the App Router.

The production pattern: separate frontmatter parsing from MDX compilation. Parse frontmatter with gray-matter at build time to generate a content index (JSON file with all posts' metadata). Then MDX compilation is a pure transform — no YAML involved. This separation means a frontmatter error never blocks MDX compilation.

import type { NextConfig } from 'next'
import createMDX from '@next/mdx'

const nextConfig: NextConfig = {
  pageExtensions: ['ts', 'tsx', 'mdx'],
  experimental: {
    mdxRs: true, // Rust-based MDX compiler — faster
  },
}

const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
})

export default withMDX(nextConfig)

Frontmatter Validation — Crash CI, Not Production

The single most important rule for MDX at scale: validate frontmatter as a prebuild step and fail CI immediately on any invalid file. Do not trust that 50 writers across your organisation will write valid YAML every time. They will not.

A Zod schema defines the exact shape of valid frontmatter: required fields (title, publishedDate, author), optional fields (tags, description, canonical), and field types (string, date, array of strings). The prebuild script reads every MDX file, parses the frontmatter with gray-matter, validates against the schema, and aggregates all errors into a single report.

The report format: file path, field name, expected type, actual value. This lets developers fix all frontmatter issues in one pass rather than fixing one file, rebuilding, discovering the next error, and iterating.

For the content pipeline, validated frontmatter feeds into a content index — a JSON file generated during prebuild that contains all posts' metadata. The Next.js app reads this index at build time to generate post listings, RSS feeds, sitemaps, and related posts. The index is the single source of truth and is guaranteed to contain only valid data because invalid files crash the build.

import { readFileSync, readdirSync } from 'fs'
import { join } from 'path'
import matter from 'gray-matter'
import { z } from 'zod'

const frontmatterSchema = z.object({
  title: z.string().min(1, 'Title is required'),
  publishedDate: z.string().regex(
    /^\d{4}-\d{2}-\d{2}$/,
    'Date must be YYYY-MM-DD'
  ),
  author: z.string().min(1),
  description: z.string().max(160).optional(),
  tags: z.array(z.string()).optional(),
  published: z.boolean().default(true),
  canonical: z.string().url().optional(),
})

type Frontmatter = z.infer<typeof frontmatterSchema>

function validateAllPosts(dir: string) {
  const errors: Array<{ file: string; error: string }> = []
  const files = readdirSync(dir, { recursive: true })
    .filter(f => (f as string).endsWith('.mdx'))

  for (const file of files) {
    const content = readFileSync(join(dir, file as string), 'utf-8')
    const { data } = matter(content)

    const result = frontmatterSchema.safeParse(data)
    if (!result.success) {
      errors.push({
        file: file as string,
        error: result.error.issues
          .map(i => `${i.path.join('.')}: ${i.message}`)
          .join('; '),
      })
    }
  }

  if (errors.length > 0) {
    console.error('\n❌ Frontmatter validation failed:')
    for (const { file, error } of errors) {
      console.error(`  ${file}: ${error}`)
    }
    process.exit(1)
  }

  console.log(`✅ All ${files.length} files passed validation`)
}

validateAllPosts('content/posts')

Draft Mode — The Headless CMS Preview Gotcha

Draft mode in Next.js lets you preview unpublished content by setting a cookie that forces ISR regeneration with draft data. Editors click 'Preview' in their headless CMS, which hits an API route that calls draftMode().enable(), then redirects to the page — which rerenders with draft content included.

The critical gotcha: draft mode ONLY works with on-demand ISR. It does NOT work with output: 'export' (static export) because static export generates all pages at build time — there are no running server instances to handle the draft cookie and trigger ISR regeneration. If your deployment uses static export for performance, draft mode cannot work.

Even within ISR, the flow requires: (1) An API route that authenticates the preview request (verify a secret token from the CMS), calls draftMode().enable(), and redirects to the page. (2) Your page or data fetching logic checks draftMode().isEnabled and includes unpublished content when true. (3) The cookie set by draftMode().enable() is HTTP-only and tied to the specific browser session — it is not shareable.

The practical implication: if your architecture demands static export (e.g., hosting on a CDN like S3+CloudFront), you need an alternative preview approach. Options: a separate preview environment (staging subdomain), client-side fetching of draft content after hydration, or a hybrid app where the CMS preview points to a separate ISR-hosted version of the same app.

import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

// CMS calls this endpoint to enable preview
// GET /api/draft?secret=MY_SECRET&slug=my-post
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const secret = searchParams.get('secret')
  const slug = searchParams.get('slug')

  // Verify secret — should match env var
  if (secret !== process.env.DRAFT_SECRET) {
    return new Response('Invalid token', { status: 401 })
  }

  if (!slug) {
    return new Response('Missing slug', { status: 400 })
  }

  // Enable draft mode — sets HTTP-only cookie
  draftMode().enable()

  // Redirect to the preview page
  redirect(`/blog/${slug}`)
}

// --- app/blog/[slug]/page.tsx ---
// Page component that checks draft mode
import { draftMode } from 'next/headers'

export default async function BlogPost({ params }: {
  params: { slug: string }
}) {
  const { isEnabled } = draftMode()

  // When draft mode is enabled, skip the published filter
  // This shows unpublished posts to the previewing editor
  const post = await getPost(params.slug, {
    includeDrafts: isEnabled,
  })

  return <Article post={post} />
}

remark and rehype Plugins — When and How to Customise the Pipeline

remark and rehype are the plugin systems for unified.js — the ecosystem for processing Markdown and HTML. remark plugins operate on the Markdown AST (mdAST) before it is compiled to HTML. rehype plugins operate on the HTML AST (hAST) after compilation.

The mental model: remark transforms your Markdown source. rehype transforms the HTML output. If you want to add syntax highlighting to code blocks, you use a remark plugin (remark-prism or remark-shiki) that wraps code blocks with syntax-highlighted HTML during the Markdown phase. If you want to add a table of contents to the rendered HTML, you use a rehype plugin (rehype-slug + rehype-toc) that operates on the final HTML.

The production insight: most sites only need 2-3 plugins. The most common are remark-gfm (GitHub-flavoured Markdown: tables, strikethrough, task lists), rehype-slug (adds IDs to headings for anchor links), and rehype-prism-plus (syntax highlighting). Each additional plugin adds ~10-50ms to build time per file — with 500 files and 5 plugins, that's 25-250 seconds of additional build time.

Plugin order matters. Some plugins depend on others: rehype-toc needs rehype-slug to have run first (headings need IDs before a TOC can reference them). Always verify the plugin documentation for ordering requirements.

import type { NextConfig } from 'next'
import createMDX from '@next/mdx'

// remark plugins (operate on Markdown AST)
import remarkGfm from 'remark-gfm'
import remarkFrontmatter from 'remark-frontmatter'
import remarkPrism from 'remark-prism'

// rehype plugins (operate on HTML AST)
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypePrism from 'rehype-prism-plus'

const nextConfig: NextConfig = {
  pageExtensions: ['ts', 'tsx', 'mdx'],
  experimental: { mdxRs: true },
}

const withMDX = createMDX({
  options: {
    remarkPlugins: [
      remarkFrontmatter,
      remarkGfm,
      remarkPrism,
    ],
    rehypePlugins: [
      rehypeSlug,          // Add IDs to headings
      [
        rehypeAutolinkHeadings,
        { behavior: 'wrap' }, // Wrap heading text in <a>
      ],
      rehypePrism,         // Syntax highlighting
    ],
  },
})

export default withMDX(nextConfig)

Content Collections — From Flat Files to Structured Data

Flat MDX files in a directory work for small blogs. For production sites with 100+ posts and multiple content types, you need a content layer — an abstraction between the file system and your pages that provides typed, filtered, and sorted post data.

The content layer reads all MDX files, parses frontmatter (validated against Zod), and builds a typed index. The index provides methods: getAllPosts(), getPostBySlug(slug), getPostsByTag(tag), getRelatedPosts(currentSlug). Each method returns typed objects with validated frontmatter and computed fields (reading time, excerpt, previous/next post).

In the App Router, this index is generated at build time and imported by pages. For static generation with generateStaticParams, the index provides the list of slugs. For ISR pages, the index provides frontmatter for SEO metadata (title, description, open graph). The index is also used server-side only — it never ships to the browser.

The performance benefit: the content index is a single JSON file loaded once at build time. No filesystem reads during page rendering — just array lookups and filters on the pre-built index. For 500 posts, filtering by tag takes microseconds instead of milliseconds per file read.

import { readFileSync, readdirSync } from 'fs'
import { join } from 'path'
import matter from 'gray-matter'
import { z } from 'zod'

const postSchema = z.object({
  slug: z.string(),
  title: z.string(),
  publishedDate: z.string(),
  author: z.string(),
  description: z.string().optional(),
  tags: z.array(z.string()).default([]),
  readingTime: z.number(),
  excerpt: z.string(),
})

export type Post = z.infer<typeof postSchema>

interface ContentIndex {
  posts: Post[]
  tags: string[]
  bySlug: Map<string, Post>
  byTag: Map<string, Post[]>
}

function buildIndex(contentDir: string): ContentIndex {
  const files = readdirSync(contentDir, { recursive: true })
    .filter(f => (f as string).endsWith('.mdx')) as string[]

  const posts: Post[] = files.map((file) => {
    const content = readFileSync(join(contentDir, file), 'utf-8')
    const { data, content: body } = matter(content)
    const slug = file.replace('.mdx', '').replace(/\\/g, '/')
    const words = body.split(/\s+/).length
    const readingTime = Math.ceil(words / 200)

    return postSchema.parse({
      slug,
      ...data,
      readingTime,
      excerpt: body.slice(0, 200).replace(/[#*`]/g, '').trim(),
    })
  })

  const bySlug = new Map(posts.map(p => [p.slug, p]))
  const byTag = new Map<string, Post[]>()

  for (const post of posts) {
    for (const tag of post.tags) {
      const existing = byTag.get(tag) ?? []
      existing.push(post)
      byTag.set(tag, existing)
    }
  }

  return {
    posts: posts.sort(
      (a, b) => b.publishedDate.localeCompare(a.publishedDate)
    ),
    tags: [...byTag.keys()].sort(),
    bySlug,
    byTag,
  }
}

export const contentIndex = buildIndex('content/posts')

Custom MDX Components — Embedding React in Markdown

MDX's killer feature is embedding React components in Markdown. A blog post about charts can drop in <RevenueChart />. A tutorial can embed <InteractiveCodeEditor />. A callout can use <Alert type="warning"> — all without leaving the Markdown file.

The mechanism: when MDX compiles, it treats HTML-like tags as React components. The components must be registered via the MDXProvider (Pages Router) or the components prop on <MDXRemote> (App Router). Unregistered components become HTML — or throw errors at build time.

In the App Router, the pattern: your page component receives the MDX content as a React element from <MDXRemote>. You pass a components object mapping tag names to React components. For example, { Alert, CodeBlock, Image }. Any <Alert> in the MDX file renders as your Alert component.

The production pattern: build a small library of reusable MDX components — callout boxes, code groups with tabs, embedded videos, data tables, interactive demos. Keep the library under 10 components. Every component must be a Server Component (no 'use client') unless it genuinely needs interactivity. Client components in MDX should be the exception, not the default.

// Server Components for MDX rendering
// These render at build time — zero JS shipped

import type { MDXComponents } from 'mdx/types'
import Link from 'next/link'

// Custom Callout component — renders as styled div
// Usage in MDX: <Callout type="warning">Content</Callout>
function Callout({
  type = 'info',
  children,
}: {
  type?: 'info' | 'warning' | 'tip' | 'danger'
  children: React.ReactNode
}) {
  const colors = {
    info: 'border-blue-500 bg-blue-50',
    warning: 'border-yellow-500 bg-yellow-50',
    tip: 'border-green-500 bg-green-50',
    danger: 'border-red-500 bg-red-50',
  }

  return (
    <div className={`border-l-4 p-4 my-6 ${colors[type]}`}>
      {children}
    </div>
  )
}

// Code Group — tabs for multi-language code blocks
// Usage in MDX:
// <CodeGroup>
// ```ts title="server.ts"
// ...
// ```
// ```py title="client.py"
// ...
// ```
// </CodeGroup>
function CodeGroup({ children }: {
  children: React.ReactNode
}) {
  return (
    <div className="code-group border rounded-lg overflow-hidden">
      {children}
    </div>
  )
}

export function useMDXComponents(): MDXComponents {
  return {
    Callout,
    CodeGroup,
    a: (props) => <Link {...props as any} />,
    // Add custom components here
  }
}

Performance at Scale — MDX for 1,000+ Posts

MDX compilation is CPU-intensive. Each file requires: parsing the Markdown into an AST, transforming the AST through each remark plugin, compiling the AST into JSX components, and transforming through rehype plugins. With mdxRs, this takes ~10-50ms per file. For 1,000 files, that's 10-50 seconds of build time for MDX compilation alone.

Strategies for scale: (1) Incremental builds — only recompile changed MDX files. Next.js's Turbopack handles this automatically in development. For production, consider a custom build pipeline that checks file modification times. (2) Separate content from rendering — precompile MDX to serialized HTML during a prebuild step, then import the static HTML in your pages. This removes MDX compilation from the next build critical path. (3) Content caching — cache the compiled output of each MDX file between builds. Only recompile files whose timestamps changed.

The most impactful optimisation: move content that doesn't need JSX to plain Markdown (processed by a simple Markdown-to-HTML converter) and reserve MDX-only for pages that genuinely embed React components. On a 1,000-post site, 800 posts may use only standard Markdown — they don't need the MDX compilation pipeline.

// Prebuild script: compile MDX to serialized HTML
// Removes MDX compilation from the next build critical path

import { readFileSync, readdirSync, writeFileSync } from 'fs'
import { join } from 'path'
import { compile } from '@mdx-js/mdx'
import matter from 'gray-matter'

async function buildContent(dir: string, outDir: string) {
  const files = readdirSync(dir, { recursive: true })
    .filter(f => (f as string).endsWith('.mdx')) as string[]

  for (const file of files) {
    const raw = readFileSync(join(dir, file), 'utf-8')
    const { content, data } = matter(raw)

    // Compile MDX to JS string
    const compiled = await compile(content, {
      outputFormat: 'function-body',
      remarkPlugins: [],
      rehypePlugins: [],
    })

    // Write compiled output + frontmatter
    const outPath = join(outDir, file.replace('.mdx', '.json'))
    writeFileSync(outPath, JSON.stringify({
      frontmatter: data,
      compiled: String(compiled),
    }))
  }
}

buildContent('content/posts', '.content-cache')

Internationalisation and MDX — Multi-Language Content

Multilingual MDX sites present unique challenges: frontmatter must support per-language titles and descriptions, translation management must not duplicate content with fs.readdirSync issues, and the sitemap must correctly route to language-specific versions.

The frontmatter approach: use a languages object in frontmatter that maps locale to title and description. The content layer builds a per-locale index. A single MDX file contains all translations, separated by locale-specific sections, or you maintain separate MDX files per locale in language-named directories.

The recommended approach: separate files per locale in a directory structure: content/en/post.mdx, content/fr/post.mdx, content/de/post.mdx. Each file has its own frontmatter. The slug is derived from the filename (shared across locales). The content layer groups files by slug and builds a per-locale index.

Performance: compilation is per-file, so 500 posts × 5 locales = 2,500 MDX compilations. The tiered approach (plain Markdown for non-React content) becomes even more important at multilingual scale. Consider using next-intl or next-i18next for runtime translations and reserve MDX for content that truly needs React components.

// Multi-locale content index
// Directory structure: content/{locale}/{slug}.mdx

import { readFileSync, readdirSync } from 'fs'
import { join } from 'path'
import matter from 'gray-matter'

const LOCALES = ['en', 'fr', 'de', 'ja'] as const
type Locale = typeof LOCALES[number]

interface LocalizedPost {
  slug: string
  locale: Locale
  title: string
  description: string
  publishedDate: string
}

function buildLocalizedIndex(baseDir: string) {
  const posts: LocalizedPost[] = []

  for (const locale of LOCALES) {
    const dir = join(baseDir, locale)
    if (!existsSync(dir)) continue

    const files = readdirSync(dir)
      .filter(f => f.endsWith('.mdx'))

    for (const file of files) {
      const content = readFileSync(join(dir, file), 'utf-8')
      const { data } = matter(content)
      const slug = file.replace('.mdx', '')

      posts.push({
        slug,
        locale,
        title: data.title,
        description: data.description ?? '',
        publishedDate: data.publishedDate,
      })
    }
  }

  return {
    posts,
    // Get all locales for a slug
    getLocalizations: (slug: string) =>
      posts.filter(p => p.slug === slug),
    // Get a specific locale + slug
    getLocalized: (slug: string, locale: Locale) =>
      posts.find(p => p.slug === slug && p.locale === locale),
  }
}

Sitemap and RSS With MDX — Automating SEO

With 200+ MDX posts, maintaining a sitemap and RSS feed manually is impossible. Next.js provides generateSitemaps() for programmatic sitemap generation, and RSS can be generated at build time from the content index.

The sitemap should include: every blog post with its lastModified date from the file system, the canonical URL, and a priority based on content freshness (newer posts = higher priority). The RSS feed should include: title, description, published date, author, and an excerpt or full content.

Both the sitemap and RSS feed are generated at build time from the content index. They should be added to robots.txt for search engine discovery. The sitemap should also include image content for posts with featured images.

The production pattern: generate the sitemap and RSS feed in a prebuild script that reads the validated content index. Output them to the public/ directory so they are served statically. This avoids runtime computation and ensures they are always in sync with the deployed content.

import { contentIndex } from '@/lib/content'

export async function GET() {
  const baseUrl = 'https://example.com'

  const posts = contentIndex.posts.map((post) => ({
    url: `${baseUrl}/blog/${post.slug}`,
    lastModified: post.publishedDate,
    changeFrequency: 'weekly' as const,
    priority: 0.8,
  }))

  const staticPages = [
    { url: baseUrl, lastModified: new Date(), changeFrequency: 'monthly' as const, priority: 1.0 },
    { url: `${baseUrl}/blog`, lastModified: new Date(), changeFrequency: 'weekly' as const, priority: 0.9 },
    { url: `${baseUrl}/about`, lastModified: new Date(), changeFrequency: 'monthly' as const, priority: 0.5 },
  ]

  const allPages = [...staticPages, ...posts]

  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  ${allPages.map((page) => `
    <url>
      <loc>${page.url}</loc>
      <lastmod>${page.lastModified}</lastmod>
      <changefreq>${page.changeFrequency}</changefreq>
      <priority>${page.priority}</priority>
    </url>`
  ).join('')}
</urlset>`

  return new Response(sitemap, {
    headers: {
      'Content-Type': 'application/xml',
    },
  })
}