Einleitung

MDX erweitert Markdown um React Components und ermöglicht damit die nahtlose Integration interaktiver Elemente in statische Inhalte. Diese Architektur verbindet die Einfachheit von Markdown mit der Flexibilität moderner Frontend-Frameworks.

Im Folgenden präsentieren wir eine Auswahl produktionserprobter Components, die wir in unseren Projekten einsetzen – mit vollständigen Implementierungsbeispielen.

Inhaltsverzeichnis

• Einleitung
• Markdown Basics – Fundamentale Syntax
• Tabs – Multi-View Content
• Accordion – Collapsed Content
• Progress Bars – Visualisierung von Metriken
• Timeline – Chronologische Darstellung
• Card Grid – Strukturierte Inhalte
• YouTube Embed – GDPR-konforme Video-Integration
• Twitter/X Quote – GDPR-konforme Tweet-Darstellung
• GitHub Repository Card – Server-Side Repo-Informationen
• Blockquote – Typografische Zitate
• Charts – Datenvisualisierung mit Recharts
• Erweiterte Chart-Beispiele
• Best Practices
• Installation
• GDPR-Compliance
• Standard Markdown Tables
• Data Tables – Strukturierte Datenvisualisierung
• Comparison Tables – Feature-Vergleiche
• Mermaid Diagrams – Flowcharts und Diagramme
• Podcast Embeds – GDPR-konforme Audio-Integration
• Callout Components – Hinweise und Markierungen
• Tooltip – Zugängliche Hover-Informationen
• Zusammenfassung

Markdown Basics – Fundamentale Syntax

Bevor wir zu den erweiterten Components kommen, hier ein Überblick über die grundlegenden Markdown-Elemente, die in jedem MDX-Dokument verfügbar sind.

Headings – Überschriften

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Text Formatting – Textformatierung

Ein Paragraph mit kursivem Text, fettem Text und inline Code.

Mehrere Paragraphs werden durch Leerzeilen getrennt.

Dies ist ein neuer Paragraph mit kombiniertem fetten und kursiven Text.

Ein Paragraph mit *kursivem Text*, **fettem Text** und `inline Code`.

Mehrere Paragraphs werden durch Leerzeilen getrennt.

Dies ist ein neuer Paragraph mit **_kombiniertem fetten und kursiven Text_**.

Lists – Listen

Unordered List:

• Erstes Element
• Zweites Element
• Drittes Element
  • Verschachteltes Element
  • Noch ein verschachteltes Element

Ordered List:

1. Erster Schritt
2. Zweiter Schritt
3. Dritter Schritt
   1. Verschachtelter Schritt
   2. Noch ein verschachtelter Schritt

* Erstes Element
* Zweites Element
  * Verschachteltes Element

1. Erster Schritt
2. Zweiter Schritt
   1. Verschachtelter Schritt

Links and Images – Links und Bilder

Ein Link zu unserer Website und ein Link mit Title.

Bilder werden automatisch responsive dargestellt und mit Grayscale-Transition versehen.

[Link Text](https://example.com)
[Link mit Title](https://example.com "Hover Title")
![Alt Text](/path/to/image.png)

Block Quote – Zitate

Dies ist ein Block Quote. Er kann verwendet werden für Zitate, wichtige Hinweise oder hervorgehobene Aussagen.

Block Quotes können mehrere Paragraphs enthalten.

> Dies ist ein Block Quote.
> 
> Mit mehreren Paragraphs.

Thematic Break – Horizontale Linie

Eine horizontale Linie zur thematischen Trennung:

Neuer Abschnitt nach der Linie.

---

Code Blocks – Code-Blöcke

Inline Code: const x = 42

Code-Block mit Syntax-Highlighting:

function greet(name) {
  console.log(`Hello, ${name}!`)
  return `Welcome to MDX`
}

const result = greet('Developer')

Verschiedene Sprachen werden unterstützt:

interface User {
  id: number
  name: string
  email: string
}

const user: User = {
  id: 1,
  name: 'John Doe',
  email: 'john@example.com'
}

.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

.button {
  background-color: #66C4E1;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.5rem;
}

Code-Syntax:

```javascript
const code = 'here'
```

Kombinierte Elemente

Ein Paragraph, der verschiedene Elemente kombiniert:

Dies ist ein wichtiger Text mit einem Link, etwas Emphasis, strong importance, und ein wenig code().

Code-Beispiel für kombinierte Elemente:

Ein **wichtiger Text** mit einem [Link](https://example.com), etwas *Emphasis*, 
**strong importance**, `code()` und ![Bilder](/image.png) inline.

Tabs – Multi-View Content

Tabs strukturieren verwandte Inhalte und reduzieren die initiale Page-Komplexität durch progressive Disclosure.

Implementation

Code

<Tabs
  tabs={[
    { label: 'Tab 1', content: <>Content 1</> },
    { label: 'Tab 2', content: <>Content 2</> },
    { label: 'Tab 3', content: <>Content 3</> },
  ]}
/>

Accordion – Collapsed Content

Accordion-Pattern für FAQ-Sections und strukturierte Informationsarchitektur.

Implementation

Code

<Accordion
  items={[
    {
      title: 'Frage 1',
      content: 'Antwort 1',
    },
    {
      title: 'Frage 2',
      content: 'Antwort 2',
    },
  ]}
/>

Progress Bars – Visualisierung von Metriken

Skill-Levels, Prozessfortschritt oder Performance-Metriken visuell darstellen.

Implementation

Code

<ProgressList
  items={[
    { label: 'React / Next.js', percentage: 95, color: 'teal' },
    { label: 'TypeScript', percentage: 90, color: 'blue' },
    { label: 'TYPO3 / PHP', percentage: 85, color: 'purple' },
    { label: 'DevOps / Cloud', percentage: 80, color: 'green' },
  ]}
/>

Timeline – Chronologische Darstellung

Projekt-Milestones, Release-History oder Entwicklungs-Roadmaps strukturiert präsentieren.

Implementation

Code

<Timeline
  items={[
    {
      date: 'Q4 2024',
      title: 'Next.js 15 Migration',
      content: 'Upgrade auf React Server Components...',
    },
    // weitere Items...
  ]}
/>

Card Grid – Strukturierte Inhalte

Cards für Features, Services oder strukturierte Informationen.

Implementation

Code

<CardGrid columns={3}>
  <Card title="Performance" variant="elevated">
    Server Components reduzieren JavaScript-Bundle-Size...
  </Card>
  <Card title="Type Safety" variant="elevated">
    Vollständige TypeScript-Integration...
  </Card>
  <Card title="Developer Experience" variant="elevated">
    Hot Module Replacement, ESLint-Integration...
  </Card>
</CardGrid>

YouTube Embed – GDPR-konforme Video-Integration

Video-Embeds ohne Cookie-Tracking vor User-Interaktion.

Implementation

Technische Details

• Nutzt react-lite-youtube-embed Library
• Lädt YouTube-Scripts erst nach User-Click
• Verwendet youtube-nocookie.com Domain
• Hover-Overlay mit Cookie-Warnung
• Vollständig responsive

Code

<YouTubeEmbed 
  id="dQw4w9WgXcQ" 
  title="Example Video" 
/>

Twitter/X Quote – GDPR-konforme Tweet-Darstellung

Statische Tweet-Darstellung ohne Tracking oder Cookies.

Implementation

Technische Details

• 100% statisches HTML - keine externen Requests
• Zero Cookies - komplette GDPR-Compliance
• Sofortiges Rendering - keine Ladezeiten
• Vollständige Kontrolle über Styling
• Link zum Original-Tweet

Code

<TweetQuote
  author="Ivan | AI | Automation"
  handle="aivanlogic"
  date="1. Oktober 2025"
  url="https://x.com/aivanlogic/status/1973332823126974657"
>
  Tweet-Text hier...
</TweetQuote>

GitHub Repository Card – Server-Side Repo-Informationen

GitHub-Repository-Daten ohne Client-Side API-Calls oder Cookie-Tracking.

Implementation

Technische Details

• Server Component mit async Data-Fetching
• Revalidierung alle 60 Minuten
• Zero Client-JavaScript erforderlich
• Keine direkten GitHub-Requests vom Browser
• ISR (Incremental Static Regeneration) Support

Code

<GitHubRepoCard owner="TYPO3" repo="typo3" />

Blockquote – Typografische Zitate

Semantisch korrekte Zitat-Darstellung mit eigenem Styling.

Implementation

"The best code is no code at all. Every line of code is a liability."

— Jeff Atwood

Code

> "The best code is no code at all."
> 
> — Jeff Atwood

Charts – Datenvisualisierung mit Recharts

Interaktive Diagramme für Metriken, Statistiken und Datenvisualisierung basierend auf der Recharts-Library.

Implementation - Line Chart

Line Charts eignen sich perfekt für Trenddarstellungen über Zeit – etwa Performance-Metriken, Umsatzentwicklung oder Nutzerwachstum.

Implementation - Bar Chart

Bar Charts ermöglichen direkten Vergleich zwischen Kategorien – ideal für Core Web Vitals, Feature-Vergleiche oder Sprint-Velocity.

Implementation - Area Chart

Area Charts visualisieren Volumen über Zeit – besonders effektiv für Traffic-Analysen, Ressourcennutzung oder Conversion-Funnels.

Implementation - Pie Chart

Pie Charts zeigen prozentuale Verteilungen – optimal für Marktanteile, Browser-Statistiken oder Kategorien-Aufteilung.

Technische Details

Unterstützte Chart-Typen:

• Line: Trends und zeitliche Entwicklungen
• Bar: Kategorischer Vergleich
• Area: Volumen-Darstellung mit Füllbereich
• Pie: Prozentuale Verteilungen

Features:

• Vollständig responsive mit ResponsiveContainer
• Automatisches Color-Management aus Brand-Palette
• Interaktive Tooltips beim Hover
• Optional: Grid, Legend, Custom Colors
• Multiple Data-Series Support
• TypeScript-typisiert

Props Overview:

• data: Array von Datenobjekten (required)
• type: Chart-Typ ('line' | 'bar' | 'area' | 'pie')
• xAxisKey: Key für X-Achse (default: 'name')
• lines/bars/areas: Array von Data-Keys für Series
• height: Chart-Höhe in Pixel (default: 400)
• showGrid: Grid-Linien anzeigen (default: true)
• showLegend: Legende anzeigen (default: true)
• colors: Custom Color-Array (optional)

Styling:

• White Background mit subtle Border
• Brand Colors: #0ea5e9, #8b5cf6, #ec4899, #f59e0b
• Responsive Container mit Padding
• Consistent mit Design-System

Code

// Data Export in MDX
export const salesData = [
  { month: 'Jan', revenue: 45000, profit: 12000 },
  { month: 'Feb', revenue: 52000, profit: 15800 },
  // ... more data
]

// Line Chart
<Chart 
  data={salesData} 
  type="line" 
  xAxisKey="month" 
  lines={['revenue', 'profit']} 
  height={400}
/>

// Bar Chart
<Chart 
  data={performanceData} 
  type="bar" 
  xAxisKey="week" 
  bars={['lcp', 'fcp', 'tti']} 
/>

// Area Chart
<Chart 
  data={trafficData} 
  type="area" 
  xAxisKey="day" 
  areas={['visitors', 'pageviews']} 
/>

// Pie Chart
<Chart 
  data={marketShareData} 
  type="pie" 
  dataKey="value" 
  xAxisKey="name" 
/>

Use Cases

Line Charts:

• Performance Metrics über Zeit (LCP, FCP, TTI)
• Umsatzentwicklung und Prognosen
• User-Growth und Retention
• API Response Times

Bar Charts:

• Framework-Vergleiche (Bundle Size, Performance)
• Sprint Velocity und Burndown
• Feature-Adoption Rates
• Error Rates nach Kategorie

Area Charts:

• Server-Ressourcen (CPU, Memory, Disk)
• Traffic-Analysen (Visitors, Sessions, Pageviews)
• Conversion Funnels
• Storage Growth

Pie Charts:

• Browser-Statistiken
• Marktanteile
• Traffic Sources
• Content-Type Distribution

Erweiterte Chart-Beispiele

Diese Sektion zeigt fortgeschrittene Recharts-Features wie Custom Dot Shapes, verschiedene Datenvisualisierungen und spezifische Use-Cases.

Line Chart mit Custom Dot Shapes

Für bessere Unterscheidbarkeit bei mehreren Datenreihen können verschiedene Punkt-Formen verwendet werden:

ROI-Entwicklung mit unterschiedlichen Punkt-Shapes für bessere Lesbarkeit

Code

export const roiData = [
  { monat: 'Monat 1', Investition: 5000, Ersparnis: 7225, Netto: 2225 },
  { monat: 'Monat 2', Investition: 5000, Ersparnis: 14450, Netto: 9450 },
  { monat: 'Monat 3', Investition: 5000, Ersparnis: 21675, Netto: 16675 },
  { monat: 'Monat 6', Investition: 5000, Ersparnis: 43350, Netto: 38350 },
  { monat: 'Monat 9', Investition: 5000, Ersparnis: 65025, Netto: 60025 },
  { monat: 'Monat 12', Investition: 5000, Ersparnis: 86700, Netto: 81700 },
]

<Chart 
  data={roiData} 
  type="line" 
  xAxisKey="monat" 
  lines={['Investition', 'Ersparnis', 'Netto']} 
  dotShapes={['cross', 'star', 'triangle']}
  height={400}
  yAxisUnit="€"
/>

Verfügbare Dot Shapes: circle, cross, diamond, square, star, triangle

Bar Chart: Vergleichsdarstellung

Vergleich von Zeitaufwand mit unterschiedlichen Prozessen:

Zeitvergleich: Manueller vs. Automatisierter Prozess

Code

export const timeComparisonData = [
  { task: 'TYPO3 Update', Manuell: 45, Automatisiert: 5 },
  { task: 'Visual Testing', Manuell: 30, Automatisiert: 2 },
  { task: 'Dokumentation', Manuell: 20, Automatisiert: 1 },
  { task: 'Ticket-Erstellung', Manuell: 15, Automatisiert: 0 },
]

<Chart 
  data={timeComparisonData} 
  type="bar" 
  xAxisKey="task" 
  bars={['Manuell', 'Automatisiert']} 
  height={350}
  yAxisUnit="Minuten"
/>

Line Chart: Multi-Series mit Diamond Dots

Skalierung und Kostenentwicklung über verschiedene Projektgrößen:

Kostenvergleich: Je mehr Projekte, desto höher die Ersparnis

Code

export const costSavingsData = [
  { projekte: '5 Projekte', Manuelle_Kosten: 21338, Automatisierte_Kosten: 1594, Ersparnis: 19744 },
  { projekte: '10 Projekte', Manuelle_Kosten: 42675, Automatisierte_Kosten: 3188, Ersparnis: 39487 },
  // ... mehr Datenpunkte
]

<Chart 
  data={costSavingsData} 
  type="line" 
  xAxisKey="projekte" 
  lines={['Manuelle_Kosten', 'Automatisierte_Kosten', 'Ersparnis']} 
  dotShapes={['circle', 'square', 'diamond']}
  height={400}
  yAxisUnit="€"
/>

Pie Chart: Zeitverteilung

Prozentuale Aufteilung von Zeitaufwand über verschiedene Tasks:

Zeitverteilung bei manuellen Update-Prozessen (110 Minuten gesamt)

Code

export const manualTimeDistribution = [
  { name: 'TYPO3 Core Update', value: 45 },
  { name: 'Visual Testing', value: 30 },
  { name: 'Dokumentation', value: 20 },
  { name: 'Ticket-Erstellung', value: 15 },
]

<Chart 
  data={manualTimeDistribution} 
  type="pie" 
  dataKey="value" 
  xAxisKey="name" 
  height={400}
  yAxisUnit="min"
/>

Area Chart: Performance-Metriken

Core Web Vitals über mehrere Wochen mit Trend-Visualisierung:

Performance-Optimierung über 6 Wochen: Kontinuierliche Verbesserung

Code

export const webVitalsData = [
  { woche: 'W1', LCP: 3.2, FID: 180, CLS: 0.25 },
  { woche: 'W2', LCP: 2.8, FID: 150, CLS: 0.20 },
  { woche: 'W3', LCP: 2.4, FID: 120, CLS: 0.15 },
  { woche: 'W4', LCP: 2.0, FID: 95, CLS: 0.10 },
  { woche: 'W5', LCP: 1.8, FID: 80, CLS: 0.08 },
  { woche: 'W6', LCP: 1.5, FID: 70, CLS: 0.05 },
]

<Chart 
  data={webVitalsData} 
  type="area" 
  xAxisKey="woche" 
  areas={['LCP', 'FID', 'CLS']} 
  height={400}
/>

Advanced: Custom Colors

Charts können mit benutzerdefinierten Farben angepasst werden:

Quartals-Umsatz mit Brand-Colors (Teal, Amber, Emerald)

Code

export const customColorData = [
  { quartal: 'Q1', Backend: 12000, Frontend: 8500, DevOps: 5200 },
  { quartal: 'Q2', Backend: 14200, Frontend: 9800, DevOps: 6100 },
  { quartal: 'Q3', Backend: 16500, Frontend: 11200, DevOps: 7500 },
  { quartal: 'Q4', Backend: 18900, Frontend: 13500, DevOps: 8900 },
]

<Chart 
  data={customColorData} 
  type="line" 
  xAxisKey="quartal" 
  lines={['Backend', 'Frontend', 'DevOps']} 
  colors={['#0e7490', '#f59e0b', '#10b981']}
  height={400}
  yAxisUnit="€"
/>

Standard Brand Colors aus colors.ts:

• Teal Dark: #0e7490 – Primary brand color
• Teal Light: #06b6d4 – Secondary emphasis
• Amber: #f59e0b – High contrast accent
• Emerald: #10b981 – Success/positive data
• Purple: #8b5cf6 – Contrasting variety
• Rose: #fb7185 – Maximum distinction

Styling Best Practices

Color Selection:

• Nutzen Sie CHART_COLOR_SETS aus @/lib/colors für konsistentes Branding
• Area Charts: CHART_COLOR_SETS.area (maximale Unterscheidbarkeit bei Überlappung)
• Line Charts: CHART_COLOR_SETS.line (knackige Distinktion)
• Bar Charts: CHART_COLOR_SETS.bar (side-by-side Klarheit)
• Pie Charts: CHART_COLOR_SETS.pie (Segment-Distinktion)

Accessibility:

• Alle Chart-Farben sind WCAG AA konform
• Minimum 3:1 Kontrast-Ratio für Farben
• Tooltips mit Hover-States für bessere Lesbarkeit
• Legend mit Icons bei Custom Dot Shapes

Performance:

• Datensätze mit >100 Punkten: Aggregation erwägen
• ResponsiveContainer für automatische Breitenanpassung
• Height explizit setzen für Layout-Stabilität

Best Practices

Performance-Optimierung

Lazy Loading

Für optimale Performance sollten Sie verstehen, wie verschiedene Component-Typen geladen werden:

Server Components (GitHubRepoCard, Timeline, Card, ProgressBar):

• Werden beim Build oder serverseitig gerendert
• Kein zusätzliches Client-JavaScript erforderlich
• Optimal für Performance

Client Components (YouTubeEmbed, TwitterEmbed, Tabs, Accordion):

• Benötigen JavaScript für Interaktivität
• Next.js splittet Code automatisch
• Werden effizient gebündelt und gecacht

Suspense Boundaries für asynchrone Inhalte:

import { Suspense } from 'react'

<Suspense fallback={<LoadingSkeleton />}>
  <TwitterEmbed id="..." />
</Suspense>

Dies verhindert weiße Bereiche während des Ladens und verbessert die User Experience signifikant.

Bundle-Size Management

• Server-First: Nutzen Sie Server Components wo möglich
• Code Splitting: Next.js splittet automatisch nach Routes
• Tree Shaking: Import nur benötigte Components
• Dynamic Imports: Für sehr große Components (optional)

Component-Auswahl

Wann welchen Component nutzen?

Tabs:

• Für verwandte Inhalte, die alternativ dargestellt werden
• Code-Beispiele in verschiedenen Sprachen
• Verschiedene Ansichten derselben Daten

Accordion:

• FAQ-Sections
• Lange Listen mit Details
• Progressive Disclosure von Informationen

Timeline:

• Projekt-Geschichte oder Roadmap
• Release-Notes
• Chronologische Prozesse

Cards:

• Feature-Übersichten
• Service-Darstellungen
• Strukturierte Content-Blocks

Progress Bars:

• Skill-Level Visualisierung
• Projekt-Fortschritt
• Metriken und KPIs

Charts:

• Zeitreihen-Analysen (Line Charts)
• Performance-Metriken über Zeit
• Vergleiche zwischen Kategorien (Bar Charts)
• Volumen-Darstellungen (Area Charts)
• Prozentuale Verteilungen (Pie Charts)
• Interaktive Daten-Exploration

DataTable:

• Strukturierte Datenvisualisierung
• Performance-Metriken und Benchmarks
• Vergleichstabellen mit Custom Formatting
• API-Dokumentation mit Parametern

ComparisonTable:

• Feature-Vergleiche zwischen Produkten
• Technology-Stack Vergleiche
• Pricing-Tabellen mit Boolean-Features
• Requirements-Checklisten

Mermaid Diagrams:

• Technische Architektur-Diagramme
• Prozess-Flows und Workflows
• Datenbank-Schemas (ER-Diagramme)
• Projekt-Timelines (Gantt)
• Sequenz-Diagramme für API-Calls

Podcast Embeds:

• Tech-Talks und Interviews
• Webinare als Audio-Versionen
• Tutorial-Serien in Podcast-Form
• Customer Testimonials als Audio

Accessibility-Guidelines

Keyboard Navigation

Alle interaktiven Components implementieren vollständige Keyboard-Support:

• Tabs: Arrow Keys für Navigation
• Accordion: Enter/Space zum Öffnen
• Buttons: Focus-Visible States

ARIA Attributes

// Beispiel: Korrekte ARIA-Implementierung
<button
  role="tab"
  aria-selected={isActive}
  aria-controls="panel-id"
/>

Screen Reader Support

• Semantic HTML verwenden
• Beschreibende Labels
• Status-Updates kommunizieren

GDPR-Compliance

External Embeds

YouTube:

• Lädt keine Scripts vor User-Interaktion
• Nutzt youtube-nocookie.com Domain
• Cookie-Warnung im Overlay

Twitter:

• Suspense-Wrapper verhindert Layout-Shift
• Skeleton während des Ladens
• Privacy-Notice unterhalb

GitHub:

• Komplett serverseitig
• Keine Client-Requests
• Zero Cookies möglich

Podcast Embeds:

• Consent-basiertes Laden
• Keine Auto-Play ohne Zustimmung
• Provider transparent kommuniziert

Code-Organisation

Empfohlene Dateistruktur

components/
├── ui/              # Basis UI Components
│   ├── Callout.tsx
│   ├── Card.tsx
│   └── Timeline.tsx
├── data/            # Data Visualization
│   ├── DataTable.tsx
│   └── MermaidDiagram.tsx
├── embeds/          # External Embeds
│   ├── YouTubeEmbed.tsx
│   ├── TwitterEmbed.tsx
│   ├── PodcastEmbed.tsx
│   └── GitHubRepoCard.tsx
└── interactive/     # Interactive Components
    ├── Tabs.tsx
    ├── Accordion.tsx
    └── ProgressBar.tsx

Type Safety

Definieren Sie klare Prop-Interfaces:

type TabItem = {
  label: string
  content: React.ReactNode
}

type TabsProps = {
  tabs: TabItem[]
  className?: string
}

// DataTable mit Generic Type Support
type DataTableColumn<T> = {
  key: keyof T
  label: string
  align?: 'left' | 'center' | 'right'
  render?: (value: T[keyof T], row: T) => React.ReactNode
}

type DataTableProps<T> = {
  columns: DataTableColumn<T>[]
  data: T[]
  variant?: 'default' | 'striped' | 'bordered' | 'minimal'
}

Testing-Strategie

• Unit Tests: Für einzelne Components
• Integration Tests: Für MDX-Integration
• Visual Regression: Für UI-Consistency
• Accessibility Tests: WCAG-Compliance prüfen

Installation

Dependencies

# Core MDX Plugins
npm install remark-gfm remark-math rehype-katex
npm install rehype-slug rehype-autolink-headings

# Embed Libraries
npm install react-lite-youtube-embed react-tweet

# Visualization Libraries
npm install mermaid recharts

# Utilities
npm install clsx

Component-spezifische Abhängigkeiten

Chart Components:

• Requires: recharts@^2.0.0
• Client-Side Rendering erforderlich
• Vollständig responsive mit ResponsiveContainer
• TypeScript-Unterstützung out-of-the-box

Mermaid Diagrams:

• Requires: mermaid@^11.0.0
• Client-Side Rendering erforderlich
• Dynamic Import für bessere Performance

Podcast Embeds:

• Keine zusätzlichen Dependencies
• Consent Management integriert
• Multiple Provider Support

DataTable Components:

• Nur clsx für Class-Management
• Vollständig TypeScript-typisiert
• Zero External Dependencies

Component-Registrierung

Components müssen in der MDX-Konfiguration registriert werden:

import { Tabs } from '@/components/Tabs'
import { Accordion } from '@/components/Accordion'
import { Timeline } from '@/components/Timeline'
import { Chart } from '@/components/Chart'
import { DataTable, ComparisonTable } from '@/components/DataTable'
import { MermaidDiagram } from '@/components/MermaidDiagram'
import { PodcastEmbed } from '@/components/PodcastEmbed'
// ... weitere imports

export const MDXComponents = {
  Tabs,
  Accordion,
  Timeline,
  Chart,
  DataTable,
  ComparisonTable,
  MermaidDiagram,
  PodcastEmbed,
  // ... weitere components
}

GDPR-Compliance

Embed-Strategie

Alle externen Embeds (YouTube, Twitter, GitHub) implementieren Privacy-by-Design:

1. YouTube: Keine Cookies ohne User-Consent
2. Twitter: Statisches Rendering ohne Tracking
3. GitHub: Server-Side Fetching ohne Browser-Requests

Data Minimization

Externe APIs nur server-side ansprechen. User-Browser kontaktiert keine Third-Party Services ohne explizite Zustimmung.

Standard Markdown Tables

Markdown-Tables werden automatisch gestylt über typography.css mit Responsive-Wrapper.

Implementation

Code

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Styling

• Automatischer Responsive Wrapper
• Border-Bottom für Rows
• Header mit stärkerem Border
• Horizontal Scroll auf Mobile
• Typography-CSS wird vererbt

Data Tables – Strukturierte Datenvisualisierung

Formatierte Tabellen für erweiterte Datenvisualisierung mit mehr Kontrolle über Styling und Verhalten. Verschiedene Variants für unterschiedliche Use-Cases.

Implementation - Standard DataTable

Implementation - Striped Variant

Technische Details

Variants:

• default: Standard mit Border und Shadow
• striped: Zebra-Streifen für bessere Lesbarkeit
• bordered: Doppelter Border für Emphasis
• minimal: Ohne Container-Styling

Features:

• Responsive Horizontal Scroll
• Custom Cell Rendering über render Function
• Alignment Control (left/center/right)
• Hover States für bessere UX
• Mobile-optimiert

Code

<DataTable
  columns={[
    { key: 'framework', label: 'Framework', align: 'left' },
    { 
      key: 'performance', 
      label: 'Performance', 
      align: 'center',
      render: (value) => (
        <span className="inline-flex gap-0.5 text-lg">
          {Array.from({ length: 5 }).map((_, i) => (
            <span key={i} className={i < value ? 'text-yellow-500' : 'text-neutral-300'}>★</span>
          ))}
        </span>
      )
    },
  ]}
  data={[
    { framework: 'Next.js', performance: 5 },
  ]}
  variant="striped"
/>

Comparison Tables – Feature-Vergleiche

Spezialisierte Tabellen für direkten Feature-Vergleich mit boolean Support und Custom Rendering.

Implementation

Technische Details

• Boolean Visualization: ✓/✕ Icons in Brand Colors
• Gradient Header: Subtiler visueller Akzent
• Hover Effects: Zeilen-Highlight für Lesbarkeit
• Responsive: Horizontal Scroll auf Mobile
• Accessibility: Semantisches Table-Markup

Code

<ComparisonTable
  headers={['Option A', 'Option B']}
  rows={[
    { label: 'Feature 1', values: [true, false] },
    { label: 'Price', values: ['€99', '€149'] },
  ]}
/>

Mermaid Diagrams – Flowcharts und Diagramme

Technische Diagramme, Flowcharts, Sequenzdiagramme und Entity-Relationship-Modelle direkt in MDX.

Implementation - Flowchart

Implementation - Sequence Diagram

Implementation - Entity Relationship

Implementation - Gantt Chart

Technische Details

Unterstützte Diagrammtypen:

• Flowchart: Prozess- und Entscheidungsflüsse
• Sequence: Interaktionen zwischen Komponenten
• Class: UML-Klassendiagramme
• State: State-Machine Diagramme
• Entity-Relationship: Datenbank-Schemas
• Gantt: Projekt-Zeitpläne
• Pie: Prozentuale Verteilungen
• Git: Branch- und Commit-Graphen

Features:

• Client-Side Rendering mit Mermaid.js
• Custom Theme mit Brand Colors
• Responsive Container
• Error Handling mit Fallback
• Caption Support
• Automatic ID Generation

Styling:

• Primary Color: #38bdf8 (Sky Blue - WCAG AA compliant)
• Text Colors: High contrast dark colors (#0c0a09 - stone-950)
• Borders & Lines: Dark grays for 3:1+ contrast (#525252, #404040)
• Secondary Background: Neutral Grays
• Font: System Sans-Serif Stack
• All colors meet WCAG 2.1 AA accessibility standards

Code

<MermaidDiagram
  chart={\`flowchart LR
    A[Start] --> B[Process]
    B --> C[End]\`}
  caption="Simple Process Flow"
/>

Podcast Embeds – GDPR-konforme Audio-Integration

Podcast-Player für Spotify, Apple Podcasts, YouTube und SoundCloud mit Privacy-by-Design und Zwei-Klick-Lösung für Datenschutz.

Implementation - Spotify

Spotify Podcasts mit standardisierter Höhe von 232px (empfohlen für optimale Darstellung):

Implementation - Apple Podcasts

Apple Podcasts mit empfohlener Höhe von 175px für kompakte Darstellung:

Implementation - YouTube (Audio/Video)

YouTube-Embeds mit Standardhöhe von 200px oder 315px für Video-Format:

Technische Details

Supported Providers:

• Spotify: Native Podcast Player (Standard: 232px Höhe)
• Apple Podcasts: iOS-optimiert (Standard: 175px Höhe)
• YouTube: Nocookie Domain für Privacy (Standard: 200px Audio / 315px Video)
• SoundCloud: Audio Streaming (Standard: 166px Höhe)
• Generic: Custom iframe URLs (flexible Höhe)

Empfohlene Heights pro Provider:

• Spotify: 232 (Standard-Player mit Cover)
• Apple Podcasts: 175 (kompakt) oder 450 (mit Episode-Liste)
• YouTube: 200 (Audio-only) oder 315 (Video 16:9)
• SoundCloud: 166 (Standard) oder 300 (mit Wellenform)

GDPR-Compliance (Zwei-Klick-Lösung):

• ✅ Consent Dialog vor Embed-Load
• ✅ Keine Cookies ohne User-Interaktion
• ✅ Provider-Name transparent kommuniziert
• ✅ Data Transfer Notification
• ✅ One-Click Opt-In
• ✅ Dekorativer Loading State mit Provider-Branding

Features:

• Lazy Loading nach Consent
• Custom Heights per Provider
• Responsive Container (100% Breite)
• Provider-Specific Branding & Colors
• Decorative Wave Pattern im Loading State
• Accessibility-optimiert (ARIA Labels)

Zusätzliches Spotify Beispiel

Ein weiteres Beispiel mit einem beliebten Tech-Podcast:

Code

<PodcastEmbed
  provider="spotify"
  episodeId="4rOoJ6Egrf8K2IrywzwOMk"
  title="Building a React Design System"
  showTitle="Syntax - Tasty Web Development Treats"
  height={232}
/>

{/* Apple Podcasts */}
<PodcastEmbed
  provider="apple"
  episodeId="show-name/id123456789"
  title="Episode Title"
  showTitle="Show Name"
  height={175}
/>

{/* YouTube Audio/Video */}
<PodcastEmbed
  provider="youtube"
  episodeId="VIDEO_ID"
  title="Video Title"
  showTitle="Channel Name"
  height={315}
/>

Rechtliche Hinweise

Urheberrecht & Lizenzen:

• Podcast-Inhalte sind urheberrechtlich geschützt
• Einbettung nur mit Genehmigung der Rechteinhaber
• Plattformen wie Spotify/Apple erlauben Embeds für auf ihren Plattformen gehostete Inhalte
• Überprüfen Sie die Terms of Service der jeweiligen Plattform
• Bei eigenen Podcasts: Copyright-Vermerk im Podcast selbst platzieren

Attribution Best Practice:

• Podcast-Titel und Creator transparent anzeigen
• Link zur Original-Plattform bereitstellen (automatisch via Player)
• Copyright-Vermerk in Beschreibung: "© 2024 [Creator Name]"

Callout Components – Hinweise und Markierungen

Callouts strukturieren wichtige Informationen visuell. Die Farbgebung ist bewusst subtil gehalten.

Available Types

Code

<Callout type="info" title="Information">
  Ihr Inhalt hier...
</Callout>

<Callout type="tip" title="Technical Tip">
  Pro-Tipps und Best Practices...
</Callout>

Tooltip – Zugängliche Hover-Informationen

Tooltips bieten kontextuelle Informationen ohne den Lesefluss zu unterbrechen. Vollständig WCAG 2.1 AA konform mit perfektem iPhone/Mobile Support.

Implementation

Tooltips können mit jedem Element verwendet werden und zeigen zusätzliche Informationen beim Hover (Desktop) oder Tap (Mobile):

Tooltips sind besonders nützlich für technische Abkürzungen oder Fachbegriffe.

Verschiedene Positionen

Technische Details

Accessibility Features:

• ✅ WCAG 2.1 Level AA konform
• ✅ Keyboard Navigation (Tab, Enter, Escape)
• ✅ Screen Reader Support (ARIA)
• ✅ Focus Management
• ✅ High Contrast (21:1 Ratio)

Mobile/iPhone Support:

• ✅ Touch-optimiert (Tap to show, tap outside to dismiss)
• ✅ Semi-transparent Backdrop auf Mobile
• ✅ Keine Hover-Probleme auf Touch-Geräten
• ✅ Responsive Positionierung

Smart Positioning:

• Bleibt immer im Viewport
• Automatische Positionsanpassung
• Responsive bei Scroll/Resize
• Konfigurierbare Seite (top/bottom/left/right)

Animation:

• Smooth Fade & Zoom
• Direktionale Slide-Animationen
• 150ms Duration für optimale UX
• Hardware-accelerated Transforms

Use Cases

Fachbegriffe erklären:

Status-Informationen:

• Verwendet in StatusBadge für Artikelstatus
• Zeigt Erklärung zu Alpha/Beta/Stable

Inline-Dokumentation:

• API-Parameter erklären
• Keyboard-Shortcuts anzeigen
• Zusätzlicher Kontext ohne Link

Code

<Tooltip content="Hilfreiche Zusatzinformation" side="top">
  <span>Element mit Tooltip</span>
</Tooltip>

{/* Mit Button */}
<Tooltip content="Aktion wird ausgeführt" side="bottom">
  <button>Hover mich</button>
</Tooltip>

{/* Inline im Text */}
Dies ist ein <Tooltip content="Erklärung hier">Fachbegriff</Tooltip> im Fließtext.

{/* Custom Delay */}
<Tooltip content="Erscheint nach 500ms" side="right" delayDuration={500}>
  <span>Verzögerter Tooltip</span>
</Tooltip>

Props:

• content: Tooltip-Text (required)
• children: Trigger-Element (required)
• side: Position ('top' | 'bottom' | 'left' | 'right', default: 'top')
• delayDuration: Verzögerung in ms (default: 200)
• className: Custom CSS Classes

Best Practices

Do ✅:

• Kurze, prägnante Texte (1-2 Sätze)
• Für ergänzende Informationen
• Bei Abkürzungen und Fachbegriffen
• Testen auf echten Mobile-Geräten

Don't ❌:

• Kritische Informationen nur im Tooltip
• Lange Texte (>100 Zeichen)
• Als Ersatz für klare UI-Labels
• Tooltips verschachteln

Zusammenfassung

Diese Component-Library deckt die häufigsten Use-Cases im Content-Management ab. Die Implementierung folgt modernen Web-Standards und priorisiert Performance, Type-Safety und GDPR-Compliance.

Alle verfügbaren Components

Markdown Basics:

• Headings: 6 Ebenen von Überschriften
• Text Formatting: Fett, Kursiv, Inline Code
• Lists: Ordered & Unordered, verschachtelt
• Links & Images: Mit automatischer Bildoptimierung
• Block Quotes: Mehrzeilige Zitate
• Code Blocks: Syntax-Highlighting für viele Sprachen
• Thematic Breaks: Horizontale Linien

Interaktive UI Components:

• Tabs: Multi-View Content mit Tab-Navigation
• Accordion: Collapsible Content für FAQs
• Progress Bars: Visualisierung von Metriken und Skills
• Timeline: Chronologische Darstellung von Events

Daten & Visualisierung:

• Chart: Line, Bar, Area und Pie Charts mit Recharts
• DataTable: Formatierte Tabellen mit mehreren Variants
• ComparisonTable: Feature-Vergleiche mit Boolean-Support
• Mermaid Diagrams: Flowcharts, Sequenzdiagramme, ER-Modelle
• Card Grid: Strukturierte Content-Blocks

Media & Embeds:

• YouTube Embed: GDPR-konforme Video-Integration
• Twitter/X Quote: Statische Tweet-Darstellung
• GitHub Repo Card: Server-Side Repository-Informationen
• Podcast Embed: Audio-Player für Spotify, Apple, YouTube

Content-Strukturierung:

• Callout: Hinweise in 5 Varianten (Info, Success, Warning, Error, Tip)
• Tooltip: Zugängliche Hover-Informationen mit Mobile-Support
• Blockquote: Typografische Zitate
• Code Blocks: Syntax-Highlighted Code mit Shiki

Technische Vorteile

• Server-First Architecture: Minimale Client-JavaScript-Last
• Type Safety: Vollständige TypeScript-Integration
• Performance: Optimiert für Core Web Vitals
• Accessibility: WCAG 2.1 AA konform
• GDPR: Privacy-by-Design Approach
• Responsive: Mobile-First Design
• Theming: Brand-Colors integriert

Ressourcen

• MDX Documentation
• Next.js MDX Guide
• React Components

Für Fragen zur Implementation: office@webconsulting.at