Zum Hauptinhalt springen

Content-Styleguide

Alle Level

Konsistenz ist es, die eine Referenz vertrauenswürdig wirken lässt. Befolge diese Punkte, und dein PR geht reibungslos durchs Review.

Tonalität​

  • Klar und direkt. Kurze Sätze. Beginne mit dem Punkt.
  • Freundlich, nie schwafelig. Streiche „in der heutigen schnelllebigen Welt". Respektiere die Zeit des Lesers.
  • Meinungsstark, dann ehrlich. Gib zuerst den einen empfohlenen Weg an, dann nenne Alternativen und Kompromisse.
  • Beispiele statt Theorie. Zeige ein Snippet oder einen konkreten Fall; beschreibe nicht nur.
  • Amerikanisches Englisch.

Aufbau einer Seite​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Beginne mit dem Level-Badge (beginner | intermediate | advanced | all). Komponenten sind global — importiere sie nicht.
  • Schließe mit einer „Weiter"-/„Verwandt"-Liste aus 2–4 internen Links ab.
  • Verwende Admonitions (:::tip, :::warning, :::note, :::info) sparsam zur Hervorhebung.

Die zwei harten Regeln​

:::warning Nicht verhandelbar

  1. Zitiere Quellen für volatile Fakten. Modellnamen, Preise, Limits, exakte Flags, Beta-Features → verlinke die offizielle Quelle und füge <VerifyNote lastVerified="YYYY-MM-DD" source="…"> hinzu. Verdrahte niemals Modellfakten fest — verlinke auf die Modelltabelle. Details: Faktenprüfung.
  2. Erfinde nichts. Keine erfundenen Statistiken, Zitate, APIs oder Features. Wenn du unsicher bist, sage es oder markiere [verify]. :::

Meinung vs. Offizielles​

  • Wir sind meinungsstark — das ist der Mehrwert. Empfehle, statt nur aufzuzählen.
  • Aber die offizielle Dokumentation ist die maßgebliche Quelle. Ordne dich ihr unter, verlinke auf sie und widerspreche ihr nie stillschweigend.

MDX-Fallstricke​

  • Geschweifte Klammern {like this} im Fließtext werden von MDX als Code geparst — setze sie in Backticks oder Code-Fences oder verwende [Klammern] in Beispielen.
  • Lokal testen: npm run build muss durchlaufen (es schlägt bei kaputten Links fehl).

Weiter​