MDX

Markdown trifft JSX – interaktive Dokumentation mit React-Komponenten.

title: "MDX – Markdown trifft React" slug: "mdx" category: "Frontend" description: "MDX kombiniert Markdown-Lesbarkeit mit React-Komponenten für interaktive Dokumentation." tags: ["MDX", "React", "Markdown", "Dokumentation", "Next.js"] navigation_path: "/tiles/mdx"

MDX – Markdown trifft React

MDX kombiniert das Beste aus zwei Welten: die Lesbarkeit von Markdown und die volle Ausdruckskraft von React-Komponenten. Du schreibst Inhalte wie in einer normalen .md-Datei, kannst aber an jeder Stelle JSX einbetten.

🪄Was diesen Artikel antreibt

Diese Seite selbst ist MDX. Das TileCallout hier, das TileGrid darunter – alles React-Komponenten, die direkt in Markdown geschrieben sind. Kein separater „embed"-Block nötig.

Wie MDX funktioniert

MDX wird zur Build-Zeit in reguläres JavaScript compiliert. Ein MDX-Compiler (z. B. @mdx-js/mdx) parst die Datei, trennt Markdown von JSX und gibt eine React-Komponente zurück, die du ganz normal importieren kannst.

Markdown-Teil

Alles was du kennst: Überschriften mit #, fett, kursiv, Listen, Links und Code-Blöcke werden 1:1 in HTML übersetzt – über konfigurierbare components auch in deine eigenen Elemente.

JSX-Teil

Überall im Dokument kannst du Komponenten einbinden. Imports am Anfang der Datei, direkte JSX-Tags im Text – alles erlaubt. Props, State und Hooks funktionieren wie in jeder anderen React-Komponente.

Setup in Next.js

Next.js unterstützt MDX out-of-the-box über @next/mdx. In der next.config.mjs aktiviert und eine mdx-components.tsx für globale Komponenten-Mappings definiert – fertig.

next.config.mjs

import createMDX from '@next/mdx'

const withMDX = createMDX({})

export default withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})

mdx-components.tsx

export function useMDXComponents(components) {
  return {
    h1: ({ children }) => (
      <h1 className="font-heading text-4xl">
        {children}
      </h1>
    ),
    ...components,
  }
}

Wann MDX wählen?

Gut geeignet für...

Dokumentationen mit interaktiven Beispielen
Blog-Artikel mit eingebetteten Demos
Design Systeme, die ihre eigenen Komponenten zeigen
Lernmaterial (z. B. dieser Digital Garden)

Weniger geeignet für...

Rein statische Inhalte ohne React-Komponenten
Inhalte, die non-technische Nutzer bearbeiten sollen
Sehr große Mengen an Dokumenten (Build-Zeiten steigen)

💡Tipp: Frontmatter

MDX unterstützt YAML-Frontmatter für Metadaten wie Titel, Datum und Tags. In Next.js kannst du diese Werte über export const metadata oder ein Remark-Plugin auslesen und für SEO oder Routing nutzen.