Lukiluki
DEEN
Menu

Ambience

Language
DEEN
Performance & Architektur
MDXReactServer ComponentsDesign System
🌐 English translation in progress – displaying original German guide.

MDX – Markdown trifft React-Komponenten

Praxiserprobter Leitfaden zu MDX in Next.js: Wie Markdown und React-Komponenten zu interaktiven Leitfäden verschmelzen – mit Live-Vorschau und Best Practices.

LKLukas Kopischke
Last updated on

Du schreibst eine technische Dokumentation in Standard-Markdown, doch sobald du einen interaktiven Rechner oder eine dynamische Vorschau einbetten willst, stößt du an die Grenzen von reinem Text: Entwickler weichen auf unleserliche iframe-Hacks oder fragile HTML-Snippets aus. Das Resultat ist entweder leblose Dokumentation oder unkoordinierter Spaghetticode.

MDX erweitert reguläres Markdown um die direkte Einbettung von React-Komponenten (JSX). Zur Build-Zeit wird die .mdx-Datei über @next/mdx in statische Server Components (RSC) kompiliert, wodurch lesbare Dokumente entstehen, die punktgenaue Client-Islands für interaktive Playgrounds ohne Hydration-Overhead laden.

Die goldene Regel

MDX macht Dokumentation lebendig: Statischer Fließtext rendert als leichtgewichtiges Server-HTML, während interaktive Komponenten punktgenau als isolierte Inseln geladen werden.

MDX Compiler & Live-Preview WorkbenchLive Werkbank
Wähle ein MDX-Muster: Begutachte den Quellcode und die unmittelbar kompilierte Server- oder Client-Ausgabe.
MDX-Quellcode
1## Architektur-Tipp
2

3Nutze MDX für technische Dokumentation:
4

5<TileCallout type="tip" title="Zero Runtime">
6  Statische Markdown-Texte rendern als reines Server-HTML.
7  Nur interaktive Inseln laden Client-JavaScript.
8</TileCallout>
Kompilierte Live-Vorschau
RSC Output
💡 Zero Runtime Tipp

Statische Markdown-Texte rendern als reines Server-HTML. Nur interaktive Inseln laden Client-JavaScript.

Wie MDX im Next.js App Router funktioniert

MDX wird während des Build-Prozesses in reguläres JavaScript und JSX übersetzt. Dadurch entstehen native React-Komponenten mit voller Typsicherheit:

1. Reines Markdown

Zero-JS

Überschriften, Absätze, Zitate und Listen werden als schlanke semantische HTML-Tags ohne Client-JavaScript gerendert.

2. Design-System Mapping

mdx-components

Über mdx-components.tsx werden Standard-Tags wie <h2> oder <code> global auf gestylte Design-System-Komponenten gemappt.

3. Isolierte Client-Islands

Interaktiv

Schwere Playgrounds werden als separate Dateien mit "use client" ausgelagert und nahtlos im Dokument eingebettet.

Do's & Don'ts: Architektonische Entscheidungen

Empfohlen (Best Practice)
  • Markdown für semantische Struktur und Fließtext nutzen
  • Interaktive Playgrounds in separate Dateien ("use client") auslagern
  • Typisierte Frontmatter-Daten per Zod-Schema zur Build-Zeit validieren
  • Globales Komponenten-Mapping via mdx-components.tsx pflegen
Zu vermeiden (Anti-Pattern)
  • useState oder Client-Hooks direkt in der .mdx-Datei deklarieren
  • H1-Überschriften (#) im Fließtext verstreuen (bricht Barrierefreiheit)
  • Riesige unoptimierte Drittbibliotheken ohne Code-Splitting in MDX importieren
  • Fragile Inline-Styles anstelle des zentralen Design-Systems verwenden
Synergie mit Design-Systemen

MDX entfaltet seine volle Stärke im Zusammenspiel mit einer gut sortierten Komponenten-Bibliothek. Erfahre mehr in unserer Übersicht zu modernen React-Komponenten-Bibliotheken.

Checkliste: MDX in der Praxis

  • Keine Client-Hooks im MDX: useState, useEffect und Event-Handler liegen in separaten Client-Dateien.
  • Saubere Überschriften: Kein # (H1) im Content vorhanden; ausschließlich ## und ### verwendet.
  • Frontmatter synchron: title, slug und description stimmen mit den System-Metadaten überein.
  • Build-Integrität gesichert: npm run build kompiliert alle MDX-Seiten fehlerfrei zu statischem HTML.
  • Plaintext-Tauglichkeit: Text bleibt auch nach dem Entfernen aller JSX-Tags für RAG-Bots vollständig lesbar.