Seminar Docusaurus – Markdown und MDX für technische Dokumentation

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Markdown-, MDX- und JSX-Modell verstehen
3. Schritt 2: Front Matter und Dokumentidentität pflegen
4. Schritt 3: Überschriften, Inhaltsübersichten und Links strukturieren
5. Schritt 4: Assets und Medien einbinden
6. Schritt 5: Code, Tabs und Hinweise gestalten
7. Schritt 6: React-Komponenten in MDX verwenden
8. Schritt 7: Diagramme, Mathematik und Spezialsyntax integrieren
9. Schritt 8: MDX-Verarbeitung erweitern und prüfen
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar vertieft die Content-Sprache von Docusaurus von sauberem Markdown bis zu kontrolliert eingesetzten MDX-Komponenten. Front Matter, Überschriften, Links, Assets, Codeblöcke, Tabs, Hinweise, Diagramme, React-Importe und Erweiterungen der Verarbeitung werden praxisnah erarbeitet.

• Markdown- und MDX-Inhalte syntaktisch korrekt und wartbar strukturieren
• Docusaurus-spezifische Content-Funktionen gezielt einsetzen
• React-Komponenten sicher in redaktionelle Inhalte integrieren
• Autorenkonventionen und Prüfregeln für konsistente Dokumentation entwickeln

Seminarinhalte

Schritt 1: Markdown-, MDX- und JSX-Modell verstehen

Markdown beschreibt Inhalt deklarativ, MDX erweitert ihn um JSX und Module. Die strengere Verarbeitung moderner MDX-Versionen verlangt klare Grenzen zwischen Text, Ausdrücken und Komponenten.

• CommonMark-Grundelemente sicher anwenden
• MDX-Ausdrücke und JSX-Syntax unterscheiden
• typische Parserfehler systematisch lokalisieren

Schritt 2: Front Matter und Dokumentidentität pflegen

Metadaten steuern Titel, Beschreibung, ID, Slug, Sidebar-Position und weitere Dokumenteigenschaften. Felder werden sparsam, typisiert und nach gemeinsamen Konventionen verwendet.

• Pflicht- und optionale Felder definieren
• stabile IDs und Slugs vergeben
• Metadaten über Vorlagen und Prüfungen vereinheitlichen

Schritt 3: Überschriften, Inhaltsübersichten und Links strukturieren

Eine logische Überschriftenhierarchie erzeugt verständliche Seitenstruktur und verlässliche Anker. Relative Links bleiben bei Versionierung und Verschiebungen robuster als hart kodierte Pfade.

• Überschriftenhierarchie und Seitentiefe begrenzen
• automatische Inhaltsübersicht kontrollieren
• Dokument- und Dateiverweise richtig wählen

Schritt 4: Assets und Medien einbinden

Dokumentnahe und globale Assets werden nach Wiederverwendung und Lebenszyklus abgelegt. Bilder erhalten passende Alternativtexte, Größen und Varianten für unterschiedliche Farbschemata.

• relative und statische Assets unterscheiden
• Bilder, Downloads und Codefragmente organisieren
• Hell- und Dunkelvarianten kontrolliert einsetzen

Schritt 5: Code, Tabs und Hinweise gestalten

Codeblöcke erhalten Sprache, Titel, Hervorhebungen und bei Bedarf Zeilennummern. Tabs und Hinweise werden nur eingesetzt, wenn sie Auswahl oder Aufmerksamkeit verbessern und auch ohne Interaktion verständlich bleiben.

• Codeblöcke mit Metadaten auszeichnen
• Varianten über synchronisierte Tabs ordnen
• Hinweistypen nach Bedeutung statt Optik wählen

Schritt 6: React-Komponenten in MDX verwenden

Komponenten werden importiert, mit klaren Props versehen und für redaktionelle Nutzung dokumentiert. Komplexe Logik bleibt außerhalb des Dokuments, damit Inhalte lesbar und überprüfbar bleiben.

• Komponenten importieren und parametrisieren
• wiederverwendbare Inhaltsbausteine gestalten
• Fehlergrenzen und zulässige Props definieren

Schritt 7: Diagramme, Mathematik und Spezialsyntax integrieren

Erweiterte Darstellungen werden über geeignete Themes oder MDX-Verarbeitung eingebunden. Quelltext, Ausgabe, Zugänglichkeit und Build-Kosten werden gemeinsam bewertet.

• Diagramm- und Mathematikbedarf abgrenzen
• Textalternativen und statische Fallbacks bereitstellen
• Verarbeitungsaufwand und Sicherheitsrisiken prüfen

Schritt 8: MDX-Verarbeitung erweitern und prüfen

Remark- und Rehype-Erweiterungen können Inhalte analysieren oder transformieren. Erweiterungen erhalten einen klaren Zweck, Tests und dokumentierte Upgrade-Grenzen.

• bestehende Erweiterungen kontrolliert konfigurieren
• einfache Transformation konzeptionell entwickeln
• Linting und Produktions-Build als Qualitätsgates einsetzen

Praxisphasen

Die einzelnen Arbeitsschritte werden an einer durchgängigen Übungsplattform umgesetzt. Konfigurationen, Inhalte und Prüfungen werden schrittweise erweitert und jeweils mit einem produktionsnahen Build kontrolliert.

• Überarbeitung einer umfangreichen technischen Seite mit Front Matter, Links, Assets und Codeblöcken
• Entwicklung eines kleinen MDX-Komponentenkatalogs mit dokumentierten Props und Anwendungsregeln
• Analyse und Behebung typischer strenger MDX-Syntax- und Build-Fehler

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionen, Entwickler, Documentation Engineers und Content-Verantwortliche mit Docusaurus-Projekten

Voraussetzungen: Grundkenntnisse in Markdown; für die MDX- und Komponentenübungen sind Grundlagen in HTML oder JSX hilfreich