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.

Video Player – Lokale Videos einbetten 

MDX ermöglicht die direkte Einbettung von HTML5-Video-Elementen für lokale Videodateien. Dies ist ideal für Demos, Tutorials und Produktpräsentationen.

Implementation 

Technische Details 

Features:

• HTML5 Native Video Player
• Vollständig responsive
• Browser-native Controls
• Keine externen Dependencies
• Optimale Performance
• Accessibility-Support durch native Player

Unterstützte Formate:

• MP4 (H.264/AAC) – beste Kompatibilität
• WebM (VP8/VP9) – moderne Alternative
• Ogg (Theora/Vorbis) – für Firefox

Best Practices:

• Immer controls Attribut setzen für Playback-Controls
• className für Tailwind CSS Styling
• Multiple <source> Tags für Browser-Fallbacks
• Descriptive fallback Text für alte Browser
• Optional: poster Image für Preview-Thumbnail
• Optional: preload="metadata" für Performance

Code 

<video 
  controls 
  className="w-full rounded-lg shadow-lg"
  style={{ maxWidth: '100%', height: 'auto' }}
>
  <source src="/path/to/video.mp4" type="video/mp4" />
  <source src="/path/to/video.webm" type="video/webm" />
  Ihr Browser unterstützt das Video-Element nicht.
</video>

Mit Poster Image:

<video 
  controls 
  poster="/path/to/thumbnail.jpg"
  className="w-full rounded-lg shadow-lg"
>
  <source src="/path/to/video.mp4" type="video/mp4" />
</video>

Props:

• controls: Zeigt Playback-Controls an (required)
• poster: Thumbnail-Bild vor dem Abspielen (optional)
• autoplay: Auto-Play (nicht empfohlen für UX)
• loop: Video wiederholt abspielen
• muted: Video stumm schalten (für autoplay erforderlich)
• preload: 'none' | 'metadata' | 'auto'
• className: Tailwind CSS Classes
• style: Inline Styles

Image Gallery – Interaktive Bildgalerien mit Lightbox 

Erstellen Sie elegante, klickbare Bildgalerien mit Lightbox-Funktionalität. Ideal für Portfolios, Projekt-Showcases und visuelle Dokumentation.

Implementation 

Die Image Gallery verwendet React Context, um Bilder zu sammeln und eine Lightbox-Slideshow zu erstellen, die beim Klick auf ein Thumbnail öffnet.

Beispiel-Verwendung in MDX:

import { MDXGallery, MDXImage } from '@/components/MDXGallery'

# Projekt-Screenshots

<MDXGallery>
  <MDXImage 
    src="/images/project-01.jpg" 
    alt="Dashboard Overview" 
    caption="Hauptansicht des Dashboards mit Analytics." 
  />
  <MDXImage 
    src="/images/project-02.jpg" 
    alt="User Management" 
    caption="Benutzerverwaltung mit Rollen und Permissions." 
  />
  <MDXImage 
    src="/images/project-03.jpg" 
    alt="Reporting Interface" 
    caption="Interaktive Reports und Datenvisualisierung." 
  />
</MDXGallery>

Technische Details 

Architektur:

• React Context Pattern: Sammelt Bild-Daten von allen <MDXImage> Komponenten
• Lazy Loading: Bilder werden erst bei Bedarf geladen
• Lightbox Integration: Fullscreen-Slideshow mit Navigation
• Thumbnail Grid: Responsive Grid-Layout für Vorschaubilder

Features:

• ✅ Click-to-Open Lightbox/Slideshow
• ✅ Keyboard Navigation (Arrow Keys, ESC)
• ✅ Swipe-Support für Mobile
• ✅ Image Captions und Alt-Text
• ✅ Lazy Loading für Performance
• ✅ Responsive Grid Layout
• ✅ Accessibility-optimiert

Empfohlene Libraries:

• react-image-lightbox: Feature-reich, gut maintained
• yet-another-react-lightbox: Modern, TypeScript-first
• fslightbox-react: Leichtgewichtig und schnell
• react-image-gallery: Vollständige Gallery mit Thumbnails

Component Implementation 

MDXGallery Component – Wrapper mit Context und State:

'use client'

import React, { useState, useCallback, createContext, useContext } from 'react'

// Context für Bilderverwaltung
const GalleryContext = createContext<{
  addImage: (image: GalleryImage) => void
  openLightbox: (id: string) => void
}>({
  addImage: () => {},
  openLightbox: () => {},
})

type GalleryImage = {
  id: string
  src: string
  alt: string
  caption?: string
}

export const MDXGallery = ({ children }: { children: React.ReactNode }) => {
  const [images, setImages] = useState<GalleryImage[]>([])
  const [isOpen, setIsOpen] = useState(false)
  const [photoIndex, setPhotoIndex] = useState(0)

  // Funktion zum Sammeln von Bildern aus Child-Components
  const addImage = useCallback((newImage: GalleryImage) => {
    setImages(currentImages => {
      // Duplikate vermeiden (wichtig für Hot Reload)
      if (!currentImages.find(img => img.src === newImage.src)) {
        return [...currentImages, newImage]
      }
      return currentImages
    })
  }, [])

  // Funktion zum Öffnen der Lightbox bei einem bestimmten Bild
  const openLightbox = useCallback((id: string) => {
    const index = images.findIndex(img => img.id === id)
    if (index !== -1) {
      setPhotoIndex(index)
      setIsOpen(true)
    }
  }, [images])

  const handleClose = () => setIsOpen(false)
  
  const handlePrev = () => {
    setPhotoIndex((photoIndex + images.length - 1) % images.length)
  }
  
  const handleNext = () => {
    setPhotoIndex((photoIndex + 1) % images.length)
  }

  const contextValue = { addImage, openLightbox }

  return (
    <GalleryContext.Provider value={contextValue}>
      {/* Thumbnail Grid */}
      <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 my-8">
        {children}
      </div>

      {/* Lightbox/Slideshow Component */}
      {isOpen && images.length > 0 && (
        <div className="fixed inset-0 z-50 bg-black bg-opacity-90 flex items-center justify-center">
          <button
            onClick={handleClose}
            className="absolute top-4 right-4 text-white text-4xl hover:text-gray-300"
            aria-label="Close gallery"
          >
            ×
          </button>
          
          <button
            onClick={handlePrev}
            className="absolute left-4 text-white text-4xl hover:text-gray-300"
            aria-label="Previous image"
          >
            ‹
          </button>
          
          <div className="max-w-5xl max-h-[90vh] p-4">
            <img
              src={images[photoIndex].src}
              alt={images[photoIndex].alt}
              className="max-w-full max-h-[80vh] object-contain"
            />
            {images[photoIndex].caption && (
              <p className="text-white text-center mt-4 text-lg">
                {images[photoIndex].caption}
              </p>
            )}
          </div>
          
          <button
            onClick={handleNext}
            className="absolute right-4 text-white text-4xl hover:text-gray-300"
            aria-label="Next image"
          >
            ›
          </button>
        </div>
      )}
    </GalleryContext.Provider>
  )
}

export const MDXImage = ({ 
  src, 
  alt, 
  caption 
}: { 
  src: string
  alt: string
  caption?: string 
}) => {
  const { addImage, openLightbox } = useContext(GalleryContext)
  
  const id = React.useMemo(() => {
    const uid = Math.random().toString(36).substring(2, 9)
    addImage({ id: uid, src, alt, caption })
    return uid
  }, [src, alt, caption, addImage])

  const handleClick = () => {
    openLightbox(id)
  }

  return (
    <div
      onClick={handleClick}
      className="cursor-pointer group relative overflow-hidden rounded-lg shadow-md hover:shadow-xl transition-shadow"
    >
      <img
        src={src}
        alt={alt}
        className="w-full h-48 object-cover group-hover:scale-105 transition-transform duration-300"
        loading="lazy"
      />
      <div className="absolute inset-0 bg-black bg-opacity-0 group-hover:bg-opacity-20 transition-opacity" />
    </div>
  )
}

Advanced: Integration mit react-image-lightbox 

Für eine professionellere Lösung empfiehlt sich yet-another-react-lightbox:

'use client'

import Lightbox from 'yet-another-react-lightbox'
import 'yet-another-react-lightbox/styles.css'
import Captions from 'yet-another-react-lightbox/plugins/captions'
import 'yet-another-react-lightbox/plugins/captions.css'

// ... (Rest des Codes bleibt gleich, aber ersetze die Lightbox-JSX mit:)

{isOpen && (
  <Lightbox
    open={isOpen}
    close={handleClose}
    index={photoIndex}
    slides={images.map(img => ({
      src: img.src,
      alt: img.alt,
      title: img.caption,
    }))}
    plugins={[Captions]}
  />
)}

Use Cases 

Projekt-Portfolios:

• Website-Screenshots in verschiedenen States
• Before/After Vergleiche
• Design-Iterationen

Dokumentation:

• UI-Component-Showcases
• Tutorial-Screenshots
• Feature-Demonstrations

Blog-Posts:

• Travel-Photography
• Event-Coverage
• Product-Reviews

Technical Docs:

• Architecture-Diagramme (hochauflösend)
• Workflow-Screenshots
• Dashboard-Mockups

Styling Best Practices 

Thumbnail Grid:

• 2 Spalten auf Mobile
• 3 Spalten auf Tablet
• 4 Spalten auf Desktop
• Konsistente Aspect-Ratios mit object-cover

Hover Effects:

• Subtle Scale Transform (1.05)
• Shadow-Intensität erhöhen
• Optional: Overlay mit Opacity

Accessibility:

• Descriptive Alt-Text für alle Bilder
• Keyboard-Navigation in Lightbox
• ESC-Key zum Schließen
• Focus-Trap in geöffneter Lightbox

Performance-Optimierung 

Lazy Loading:

Next.js Image Optimization:

Progressive Enhancement:

• Thumbnails in WebP-Format
• Fullsize-Images erst bei Lightbox-Open laden
• Skeleton-Loader für langsame Verbindungen

Inhaltsverzeichnis 

• Einleitung
• Video Player – Lokale Videos einbetten
• Image Gallery – Interaktive Bildgalerien mit Lightbox
• 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
• PDF Download – Konsistente Download-Links
• Subpage Navigator – Content-Navigation
• 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

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.

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

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.

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.

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:

Verschiedene Sprachen werden unterstützt:

Code-Syntax:

<CodeBlock language="javascript">{`const code = 'here'`}</CodeBlock>

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:

Tabs – Multi-View Content 

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

Implementation 

Code 

Neue MDX-Syntax (empfohlen) – unterstützt vollständiges MDX inkl. Code-Blocks:

<Tabs>
  <Tab label="TypeScript">

<CodeBlock language="typescript">{`async function fetchData<T>(url: string): Promise<T> {
  const response = await fetch(url)
  return response.json()
}`}</CodeBlock>

  </Tab>
  <Tab label="JavaScript">

<CodeBlock language="javascript">{`async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}`}</CodeBlock>

  </Tab>
</Tabs>

Alternative JSX-Array-Syntax (für einfache Inhalte ohne MDX):

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

MDX Tab-Content – Best Practices 

Mit der neuen <Tab>-Syntax können Sie vollständiges MDX verwenden:

Syntax-Regel für MDX in Tabs:

⚠️ Wichtige Best Practices für Tabs 

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 

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

Image Gallery:

• Projekt-Portfolios mit Screenshots
• Before/After Vergleiche bei Redesigns
• Tutorial-Screenshots in Dokumentation
• Event-Coverage und Photo-Essays
• Product-Showcases mit Multiple Views
• Architecture-Diagramme in High-Resolution

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:

Flowchart:

• Prozess-Dokumentation und Geschäftsprozesse
• Entscheidungsbäume und Algorithmen
• User-Flows und Navigation
• Deployment-Pipelines

Sequence Diagram:

• API-Interaktionen und Request-Flows
• Microservice-Kommunikation
• Authentication-Prozesse
• Event-basierte Systeme

Class Diagram:

• Software-Architektur und Design Patterns
• Object-Oriented Programming Strukturen
• Domain Models
• API-Schnittstellen

State Diagram:

• Workflow-Management und Approval-Prozesse
• Content-Publishing States
• Order-Processing Status
• Application-Lifecycles

Entity Relationship Diagram:

• Datenbank-Schema-Dokumentation
• Datenmodelle und Beziehungen
• Migration-Planung
• Legacy-System-Analyse

User Journey:

• Customer Experience Mapping
• UX-Optimierung und Conversion-Flows
• Onboarding-Prozesse
• Multi-Channel Customer Touchpoints

Gantt Chart:

• Projekt-Zeitpläne und Milestones
• Sprint-Planung und Release-Schedules
• Ressourcen-Planung
• Dependency-Management

Pie Chart:

• Browser- und Device-Statistiken
• Marktanteils-Visualisierung
• Budget-Verteilungen
• Traffic-Source-Analysen

Git Graph:

• Branching-Strategien dokumentieren
• Release-Flow visualisieren
• Merge-Strategien erklären
• Contribution-History

Mindmap:

• Technologie-Stack Übersichten
• Brainstorming-Sessions
• Wissensstrukturen und Taxonomien
• Feature-Planning und Ideation

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 

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

Image Gallery:

• Requires: yet-another-react-lightbox@^3.0.0 (empfohlen)
• Alternatives: react-image-lightbox, fslightbox-react
• Client-Side Rendering für Interaktivität
• React Context für State-Management
• TypeScript-Support verfügbar

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'
import { MDXGallery, MDXImage } from '@/components/MDXGallery'
import { CodeBlock } from '@/components/CodeBlock'
// ... weitere imports

export const MDXComponents = {
  Tabs,
  Accordion,
  Timeline,
  Chart,
  DataTable,
  ComparisonTable,
  MermaidDiagram,
  PodcastEmbed,
  MDXGallery,
  MDXImage,
  // ... 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 

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 

Implementation - Class Diagram 

Implementation - State Diagram 

Implementation - User Journey 

Implementation - Pie Chart 

Implementation - Git Graph 

Implementation - Mindmap 

Technische Details 

Unterstützte Diagrammtypen:

• Flowchart: Prozess- und Entscheidungsflüsse
• Sequence: Interaktionen zwischen Komponenten
• Class: UML-Klassendiagramme und Object-Oriented Design
• State: State-Machine Diagramme und Workflow-Übergänge
• Entity-Relationship: Datenbank-Schemas und Datenmodelle
• User Journey: UX-Flows und Customer Journey Maps
• Gantt: Projekt-Zeitpläne und Milestones
• Pie: Prozentuale Verteilungen und Statistiken
• Git Graph: Branch-Strategien und Commit-History
• Mindmap: Brainstorming, Wissensstrukturen und Hierarchien

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 

⚠️ Best Practices für Callouts 

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

PDF Download – Konsistente Download-Links 

Einheitliche Darstellung für PDF-Downloads in Blog-Posts. Mit Icon, Dateigröße und verschiedenen Varianten.

Implementation - Default Variant 

Die Standard-Variante ist prominent und lädt zum Download ein.

Implementation - Compact Variant 

Für inline-Verwendung im Text: Material als PDF(2.3 MB) – ideal für Fließtext.

Implementation - Card Variant 

Die Card-Variante eignet sich für prominente Downloads mit ausführlicher Beschreibung.

Technische Details 

Variants:

• default: Standard mit Icon und Hover-Effekt
• compact: Inline-Version für Fließtext
• card: Prominente Card mit Beschreibung

Features:

• Automatisches PDF-Icon
• Dateigröße-Anzeige (optional)
• Beschreibungstext (optional)
• Hover-Animationen
• Externe Links (target="_blank")
• Konsistentes Styling

Code 

{/* Default Variant */}
<PDFDownload 
  url="/pdfs/meine-serie/original.pdf"
  title="Material herunterladen"
  description="Vollständiges Lehrmaterial"
  fileSize="2.3 MB"
/>

{/* Compact Inline */}
Text mit <PDFDownload 
  url="/path/to/file.pdf"
  title="PDF"
  fileSize="1.2 MB"
  variant="compact"
/> inline.

{/* Card Variant */}
<PDFDownload 
  url="/pdfs/meine-serie/original.pdf"
  title="Vollständiges Kursmaterial"
  description="Alle Themen, Übungen und Hintergrundinformationen"
  fileSize="5.8 MB"
  variant="card"
/>

Props:

• url: Pfad zur PDF-Datei (required)
• title: Titel des Downloads (default: "PDF herunterladen")
• description: Beschreibung (optional)
• fileSize: Dateigröße z.B. "2.3 MB" (optional)
• variant: 'default' | 'compact' | 'card' (default: 'default')

Use Cases 

Default Variant:

• Wichtige Materialien am Anfang/Ende eines Artikels
• Zusätzliche Ressourcen in der Sidebar
• Download-Links in Lernmaterialien

Compact Variant:

• Inline im Fließtext
• Listen mit mehreren Downloads
• Referenzen in Fußnoten

Card Variant:

• Haupt-Download einer Serie
• Prominente Platzierung auf Übersichtsseiten
• Komplette Kursmaterialien

Integration mit PDF-zu-Blog-System 

Die PDFDownload-Komponente ist optimal für das PDF-zu-Blog-System:

Subpage Navigator – Content-Navigation 

Strukturierte Navigation zu verwandten Unterseiten mit einem 2-spaltigen Card-Grid. Perfekt für Blog-Serien, Lernmaterialien und hierarchische Content-Strukturen.

Implementation - 2-Spalten Layout 

Der SubpageNavigator macht die gesamte Card klickbar und bietet hover-Effekte für bessere User Experience.

Implementation - 3-Spalten Layout 

Die 3-Spalten-Variante eignet sich für kompaktere Darstellungen mit mehr Items.

Implementation - Ohne Nummerierung 

Nummerierung ist optional – ideal für nicht-sequentielle Inhalte.

Technische Details 

Features:

• Gesamte Card ist klickbar (Link umschließt komplette Border)
• Smooth Hover-Effekte (Border-Color, Text-Color, Arrow-Translation)
• Optional: Nummerierung für sequentielle Inhalte
• Responsive Grid: 1, 2 oder 3 Spalten
• Fade-In Animation für bessere UX
• Accessibility-optimiert mit ARIA-Labels
• "Mehr erfahren" Indikator mit animiertem Arrow

Column Options:

• 1: Einzelne Spalte (volle Breite)
• 2: 2 Spalten ab lg Breakpoint (Standard)
• 3: 2 Spalten ab md, 3 ab lg Breakpoint

Item Props:

• title: Card-Titel (required)
• href: Link-Ziel (required)
• description: Beschreibungstext (required)
• number: Optionale Nummerierung z.B. "01", "02"

Styling:

• Konsistent mit bestehenden Border-Components
• Hover-Effekte auf Border, Title und Description
• Arrow-Icon mit Translation-Animation
• Grayscale-to-Color Transition (wie andere Cards)
• Fully responsive Grid-Layout

Use Cases 

Blog-Serien:

• Lernmaterial-Serien (wie "Wahr oder falsch im Internet?")
• Tutorial-Reihen mit mehreren Teilen
• Thematisch zusammenhängende Artikel

Dokumentation:

• API-Dokumentation mit Unterseiten
• Getting Started Guides
• Feature-Übersichten

Hierarchische Navigation:

• Unterseiten eines Hauptthemas
• Modul-Übersichten in Kursen
• Kapitel in längeren Inhalten

Code 

<SubpageNavigator
  items={[
    {
      title: "Titel der Unterseite",
      href: "/pfad/zur/unterseite",
      description: "Beschreibung was den Leser auf dieser Seite erwartet.",
      number: "01" // Optional
    },
    {
      title: "Zweite Unterseite",
      href: "/pfad/zur/zweiten-seite",
      description: "Weitere Informationen zu einem verwandten Thema."
    }
  ]}
  columns={2} // 1, 2 oder 3
/>

Beispiel mit React-Daten:

export const navigationItems = [
  {
    title: "Getting Started",
    href: "/docs/getting-started",
    description: "Learn the basics and get up and running.",
    number: "01"
  },
  {
    title: "Advanced Topics",
    href: "/docs/advanced",
    description: "Deep dive into advanced features.",
    number: "02"
  }
]

<SubpageNavigator items={navigationItems} columns={2} />

Best Practices 

Do ✅:

• Nutze Nummerierung für sequentielle Inhalte (Tutorial-Reihen)
• Halte Beschreibungen kurz und aussagekräftig (1-2 Sätze)
• Verwende konsistente URL-Struktur für verwandte Seiten
• Wähle 2 Spalten für ausführlichere Beschreibungen
• Wähle 3 Spalten für kompaktere Darstellung mit mehr Items

Don't ❌:

• Zu lange Titel (>60 Zeichen)
• Zu lange Beschreibungen (>150 Zeichen)
• Mixing nummerierte und nicht-nummerierte Items
• Mehr als 12 Items in einem Navigator (besser aufteilen)

Integration mit bestehenden Patterns 

Der SubpageNavigator ergänzt perfekt bestehende Components:

Accessibility 

Keyboard Navigation:

• Vollständig Tab-navigierbar
• Enter/Space aktiviert Links
• Focus-Visible States

Screen Reader Support:

• Semantic HTML (<Link>, <article>)
• Descriptive ARIA-Labels
• Clear Heading Structure

Visual Indicators:

• High Contrast Border (3:1 Ratio)
• Hover States für bessere Affordance
• Arrow-Icon als visueller CTA

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, Sequence, Class, State, ER, User Journey, Gantt, Pie, Git Graph, Mindmap
• Card Grid: Strukturierte Content-Blocks

Media & Embeds:

• Video Player: HTML5 Native Video mit Controls
• Image Gallery: Interaktive Lightbox-Galerien mit Thumbnails
• 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
• PDF Download: Konsistente Download-Links mit 3 Varianten
• Subpage Navigator: 2-spaltiges Grid für Navigation zu Unterseiten

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
• Mermaid.js Documentation - Diagramming and charting tool
• Recharts Documentation - Chart library

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