Leitfaden für Dokumentationsbeiträge

Willkommen beim Next.js-Dokumentationsbeitragsleitfaden! Wir freuen uns, dass Sie hier sind.

Diese Seite enthält Anleitungen, wie Sie die Next.js-Dokumentation bearbeiten können. Unser Ziel ist es, dass sich jeder in der Community ermutigt fühlt, Beiträge zu leisten und unsere Dokumentation zu verbessern.

Warum Beitragen?

Open-Source-Arbeit ist niemals abgeschlossen, und das gilt auch für Dokumentation. Das Mitwirken an der Dokumentation ist eine gute Möglichkeit für Anfänger, sich in Open-Source zu engagieren, und für erfahrene Entwickler, komplexere Themen zu klären und ihr Wissen mit der Community zu teilen.

Indem Sie zur Next.js-Dokumentation beitragen, helfen Sie uns, eine robustere Lernressource für alle Entwickler aufzubauen. Egal, ob Sie einen Tippfehler gefunden haben, einen unklaren Abschnitt oder festgestellt haben, dass ein bestimmtes Thema fehlt – Ihre Beiträge sind willkommen und werden geschätzt.

Wie Sie Beitragen können

Die Dokumentationsinhalte finden Sie im Next.js-Repo. Um Beiträge zu leisten, können Sie die Dateien direkt auf GitHub bearbeiten oder das Repo klonen und die Dateien lokal bearbeiten.

GitHub-Workflow

Wenn Sie neu bei GitHub sind, empfehlen wir Ihnen, den GitHub Open Source Guide zu lesen, um zu lernen, wie Sie ein Repository forken, einen Branch erstellen und einen Pull Request einreichen.

Gut zu wissen: Der zugrundeliegende Dokumentationscode befindet sich in einer privaten Codebasis, die mit dem öffentlichen Next.js-Repo synchronisiert wird. Das bedeutet, dass Sie die Dokumentation nicht lokal vorschauen können. Sie werden Ihre Änderungen jedoch auf nextjs.org sehen, nachdem ein Pull Request gemergt wurde.

MDX schreiben

Die Dokumentation ist in MDX geschrieben, einem Markdown-Format, das JSX-Syntax unterstützt. Dadurch können wir React-Komponenten in die Dokumentation einbetten. Siehe den GitHub Markdown Guide für einen schnellen Überblick über die Markdown-Syntax.

VSCode

Lokale Vorschau von Änderungen

VSCode hat einen integrierten Markdown-Previewer, den Sie verwenden können, um Ihre Bearbeitungen lokal anzuzeigen. Um den Previewer für MDX-Dateien zu aktivieren, müssen Sie eine Konfigurationsoption zu Ihren Benutzereinstellungen hinzufügen.

Öffnen Sie die Befehlspalette (⌘ + ⇧ + P auf Mac oder Ctrl + Shift + P auf Windows) und suchen Sie nach Preferences: Open User Settings (JSON).

Fügen Sie dann die folgende Zeile zu Ihrer settings.json-Datei hinzu:

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Öffnen Sie die Befehlspalette erneut und suchen Sie nach Markdown: Preview File oder Markdown: Open Preview to the Side. Dadurch wird ein Vorschaufenster geöffnet, in dem Sie Ihre formatierten Änderungen sehen können.

Erweiterungen

Wir empfehlen auch die folgenden Erweiterungen für VSCode-Benutzer:

• MDX: Intellisense und Syntax-Highlighting für MDX.
• Grammarly: Grammatik- und Rechtschreibprüfung.
• Prettier: Formatierung von MDX-Dateien beim Speichern.

Review-Prozess

Sobald Sie Ihren Beitrag eingereicht haben, werden die Next.js- oder Developer-Experience-Teams Ihre Änderungen überprüfen, Feedback geben und den Pull Request mergen, wenn er fertig ist.

Bitte teilen Sie uns in den Kommentaren Ihres PRs mit, wenn Sie Fragen haben oder weitere Hilfe benötigen. Vielen Dank, dass Sie zur Next.js-Dokumentation beitragen und Teil unserer Community sind!

Tipp: Führen Sie pnpm prettier-fix aus, um Prettier vor dem Einreichen Ihres PRs auszuführen.

Dateistruktur

Die Dokumentation verwendet File-System Routing. Jeder Ordner und jede Datei innerhalb von /docs repräsentiert ein Routensegment. Diese Segmente werden verwendet, um die URL-Pfade, die Navigation und die Breadcrumbs zu generieren.

Die Dateistruktur spiegelt die Navigation wider, die Sie auf der Website sehen, und standardmäßig sind die Navigationselemente alphabetisch sortiert. Wir können die Reihenfolge der Elemente jedoch ändern, indem wir eine zweistellige Zahl (00-) dem Ordnernamen oder Dateinamen voranstellen.

Beispielsweise sind in der Functions API Reference die Seiten alphabetisch sortiert, weil es Entwicklern so leichter fällt, eine bestimmte Funktion zu finden:

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

Aber im Routing-Bereich sind die Dateien mit einer zweistelligen Zahl versehen, sortiert in der Reihenfolge, in der Entwickler diese Konzepte lernen sollten:

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

Um schnell eine Seite zu finden, können Sie ⌘ + P (Mac) oder Ctrl + P (Windows) verwenden, um die Suchleiste in VSCode zu öffnen. Geben Sie dann den Slug der gesuchten Seite ein, z.B. defining-routes.

Warum kein Manifest verwenden?

Wir haben darüber nachgedacht, eine Manifest-Datei (eine andere beliebte Methode zur Generierung der Dokumentationsnavigation) zu verwenden, aber wir haben festgestellt, dass ein Manifest schnell nicht mehr mit den Dateien synchron wäre. File-System Routing zwingt uns, über die Struktur der Dokumentation nachzudenken, und fühlt sich für Next.js natürlicher an.

Metadaten

Jede Seite hat einen Metadatenblock am Anfang der Datei, der durch drei Bindestriche getrennt ist.

Erforderliche Felder

Die folgenden Felder sind erforderlich:

---
title: Seitentitel
description: Seitenbeschreibung
---

Es ist eine gute Praxis, den Seitentitel auf 2-3 Wörter zu beschränken (z.B. "Bilder optimieren") und die Beschreibung auf 1-2 Sätze (z.B. "Erfahren Sie, wie Sie Bilder in Next.js optimieren können").

Optionale Felder

Die folgenden Felder sind optional:

---
nav_title: Navigationspunkt-Titel
source: app/building-your-application/optimizing/images
related:
  description: Siehe die API-Referenz der Image-Komponente.
  links:
    - app/api-reference/components/image
---

App- und Pages-Dokumentation

Da die meisten Funktionen im App Router und Pages Router völlig unterschiedlich sind, werden ihre Dokumentationen in separaten Abschnitten (02-app und 03-pages) gehalten. Es gibt jedoch einige Funktionen, die beiden gemeinsam sind.

Gemeinsame Seiten

Um Inhaltsduplizierung und das Risiko zu vermeiden, dass Inhalte nicht mehr synchron sind, verwenden wir das source-Feld, um Inhalte von einer Seite in eine andere zu pullen. Beispielsweise verhält sich die <Link>-Komponente in App und Pages größtenteils gleich. Anstatt den Inhalt zu duplizieren, können wir den Inhalt von app/.../link.mdx in pages/.../link.mdx pullen:

---
title: <Link>
description: API-Referenz für die <Link>-Komponente.
---

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die Props
und Konfigurationsoptionen der Link-Komponente verwenden können.

---
title: <Link>
description: API-Referenz für die <Link>-Komponente.
source: app/api-reference/components/link
---

{/* DIESE SEITE NICHT BEARBEITEN. */}
{/* Der Inhalt dieser Seite wird von der oben genannten Quelle gepullt. */}

Wir können den Inhalt also an einer Stelle bearbeiten und er wird in beiden Abschnitten aktualisiert.

Gemeinsame Inhalte

In gemeinsamen Seiten kann es manchmal Inhalte geben, die spezifisch für den App Router oder Pages Router sind. Beispielsweise hat die <Link>-Komponente eine shallow-Prop, die nur in Pages, aber nicht in App verfügbar ist.

Um sicherzustellen, dass der Inhalt nur im richtigen Router angezeigt wird, können wir Inhaltsblöcke in <AppOnly>- oder <PagesOnly>-Komponenten einwickeln:

Dieser Inhalt wird von App und Pages gemeinsam genutzt.

<PagesOnly>

Dieser Inhalt wird nur in der Pages-Dokumentation angezeigt.

</PagesOnly>

Dieser Inhalt wird von App und Pages gemeinsam genutzt.

Sie werden diese Komponenten wahrscheinlich für Beispiele und Codeblöcke verwenden.

Codeblöcke

Codeblöcke sollten ein minimal funktionierendes Beispiel enthalten, das kopiert und eingefügt werden kann. Das bedeutet, dass der Code ohne zusätzliche Konfiguration ausgeführt werden können sollte.

Wenn Sie beispielsweise zeigen, wie die <Link>-Komponente verwendet wird, sollten Sie die import-Anweisung und die <Link>-Komponente selbst einbeziehen.

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Führen Sie Beispiele immer lokal aus, bevor Sie sie committen. Dadurch wird sichergestellt, dass der Code aktuell und funktionsfähig ist.

Sprache und Dateiname

Codeblöcke sollten eine Kopfzeile mit der Sprache und dem filename enthalten. Fügen Sie eine filename-Prop hinzu, um ein spezielles Terminal-Symbol zu rendern, das Benutzern hilft, zu erkennen, wo sie den Befehl eingeben sollen. Beispiel:

```bash filename="Terminal"
npx create-next-app
```

Die meisten Beispiele in der Dokumentation sind in tsx und jsx geschrieben, einige in bash. Sie können jedoch jede unterstützte Sprache verwenden, hier ist die vollständige Liste.

Wenn Sie JavaScript-Codeblöcke schreiben, verwenden wir die folgenden Sprach- und Erweiterungskombinationen.

TS- und JS-Switcher

Fügen Sie einen Sprach-Switcher hinzu, um zwischen TypeScript und JavaScript zu wechseln. Codeblöcke sollten zuerst in TypeScript mit einer JavaScript-Version für Benutzer sein.

Derzeit schreiben wir TS- und JS-Beispiele nacheinander und verknüpfen sie mit der switcher-Prop:

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

Gut zu wissen: Wir planen, TypeScript-Snippets in Zukunft automatisch in JavaScript zu kompilieren. In der Zwischenzeit können Sie transform.tools verwenden.

Zeilenhervorhebung

Codezeilen können hervorgehoben werden. Dies ist nützlich, wenn Sie die Aufmerksamkeit auf einen bestimmten Teil des Codes lenken möchten. Sie können Zeilen hervorheben, indem Sie eine Zahl an die highlight-Prop übergeben.

Einzelne Zeile: highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Mehrere Zeilen: highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Zeilenbereich: highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Symbole

Die folgenden Symbole sind in der Dokumentation verfügbar:

<Check size={18} />
<Cross size={18} />

Ausgabe:

Wir verwenden keine Emojis in der Dokumentation.

Hinweise

Für Informationen, die wichtig, aber nicht kritisch sind, verwenden Sie Hinweise. Hinweise sind eine gute Möglichkeit, Informationen hinzuzufügen, ohne den Benutzer vom Hauptinhalt abzulenken.

> **Gut zu wissen**: Dies ist ein einzeiliger Hinweis.

> **Gut zu wissen**:
>
> - Wir verwenden dieses Format auch für mehrzeilige Hinweise.
> - Manchmal gibt es mehrere Punkte, die es wert sind, bekannt zu sein oder im Hinterkopf zu behalten.

Ausgabe:

Gut zu wissen: Dies ist ein einzeiliger Hinweis.

Gut zu wissen:

• Wir verwenden dieses Format auch für mehrzeilige Hinweise.
• Manchmal gibt es mehrere Punkte, die es wert sind, bekannt zu sein oder im Hinterkopf zu behalten.

Verwandte Links

Verwandte Links leiten den Lernprozess des Benutzers, indem sie Links zu logischen nächsten Schritten hinzufügen.

• Links werden in Karten unter dem Hauptinhalt der Seite angezeigt.
• Links werden automatisch für Seiten generiert, die Unterseiten haben. Beispielsweise hat der Optimierungsbereich Links zu all seinen Unterseiten.

Erstellen Sie verwandte Links mit dem related-Feld in den Metadaten der Seite.

---
related:
  description: Erfahren Sie, wie Sie schnell mit Ihrer ersten Anwendung beginnen können.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

Verschachtelte Felder

Diagramme

Diagramme sind eine großartige Möglichkeit, komplexe Konzepte zu erklären. Wir verwenden Figma, um Diagramme zu erstellen, und folgen dabei dem Vercel-Design-Leitfaden.

Die Diagramme befinden sich derzeit in einem /public-Ordner in unserer privaten Next.js-Site. Wenn Sie ein Diagramm aktualisieren oder hinzufügen möchten, öffnen Sie bitte ein GitHub-Issue mit Ihren Ideen.

Benutzerdefinierte Komponenten und HTML

Dies sind die React-Komponenten, die für die Dokumentation verfügbar sind: <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross /> und <Check />. Wir erlauben kein rohes HTML in der Dokumentation außer dem <details>-Tag.

Wenn Sie Ideen für neue Komponenten haben, öffnen Sie bitte ein GitHub-Issue.

Style-Guide

Dieser Abschnitt enthält Richtlinien für das Schreiben von Dokumentationen für diejenigen, die neu im technischen Schreiben sind.

Seitentemplates

Während wir kein strenges Template für Seiten haben, gibt es Seitenabschnitte, die Sie in der gesamten Dokumentation wiederholt sehen werden:

• Überblick: Der erste Absatz einer Seite sollte dem Benutzer sagen, was die Funktion ist und wofür sie verwendet wird. Gefolgt von einem minimal funktionierenden Beispiel oder seiner API-Referenz.
• Konvention: Wenn die Funktion eine Konvention hat, sollte sie hier erklärt werden.
• Beispiele: Zeigen Sie, wie die Funktion mit verschiedenen Anwendungsfällen verwendet werden kann.
• API-Tabellen: API-Seiten sollten eine Übersichtstabelle am Ende der Seite mit Sprunglinks (wenn möglich) haben.
• Nächste Schritte (Verwandte Links): Fügen Sie Links zu verwandten Seiten hinzu, um den Lernprozess des Benutzers zu leiten.

Fügen Sie diese Abschnitte nach Bedarf hinzu.

Seitentypen

Die Dokumentationsseiten sind ebenfalls in zwei Kategorien unterteilt: Konzeptionelle Seiten und Referenzseiten.

• Konzeptionelle Seiten dienen dazu, ein Konzept oder eine Funktion zu erklären. Sie sind in der Regel länger und enthalten mehr Informationen als Referenzseiten. In der Next.js-Dokumentation finden Sie konzeptionelle Seiten im Abschnitt Building Your Application (Anwendung erstellen).
• Referenzseiten dienen dazu, eine spezifische API zu erklären. Sie sind in der Regel kürzer und fokussierter. In der Next.js-Dokumentation finden Sie Referenzseiten im Abschnitt API Reference (API-Referenz).

Gut zu wissen: Je nach Seite, zu der Sie beitragen, müssen Sie möglicherweise einen anderen Stil und Tonfall verwenden. Konzeptionelle Seiten sind beispielsweise eher anleitend und verwenden das Wort Sie, um den Benutzer anzusprechen. Referenzseiten sind technischer, verwenden mehr imperative Wörter wie "erstellen, aktualisieren, akzeptieren" und lassen das Wort Sie oft weg.

Stil und Tonfall

Hier sind einige Richtlinien, um einen einheitlichen Stil und Tonfall in der Dokumentation beizubehalten:

• Schreiben Sie klare, prägnante Sätze. Vermeiden Sie Abschweifungen.
  • Wenn Sie viele Kommas verwenden, sollten Sie den Satz in mehrere Sätze aufteilen oder eine Liste verwenden.
  • Ersetzen Sie komplexe Wörter durch einfachere. Zum Beispiel verwenden statt nutzen.
• Seien Sie vorsichtig mit dem Wort dies. Es kann mehrdeutig und verwirrend sein. Scheuen Sie sich nicht, das Subjekt des Satzes zu wiederholen, wenn es unklar ist.
  • Zum Beispiel: Next.js verwendet React statt Next.js verwendet dies.
• Verwenden Sie aktive statt passive Formulierungen. Ein aktiver Satz ist leichter zu lesen.
  • Zum Beispiel: Next.js verwendet React statt React wird von Next.js verwendet. Wenn Sie Wörter wie wird und von verwenden, könnte es sich um eine passive Formulierung handeln.
• Vermeiden Sie Wörter wie einfach, schnell, unkompliziert, einfach nur usw. Diese sind subjektiv und können für Benutzer entmutigend sein.
• Vermeiden Sie negative Wörter wie nicht, kann nicht, wird nicht usw. Diese können Leser entmutigen.
  • Zum Beispiel: "Sie können die Link-Komponente verwenden, um Links zwischen Seiten zu erstellen" statt "Verwenden Sie nicht das <a>-Tag, um Links zwischen Seiten zu erstellen".
• Schreiben Sie in der zweiten Person (Sie/Ihr). Das ist persönlicher und ansprechender.
• Verwenden Sie geschlechtsneutrale Sprache. Verwenden Sie Entwickler, Benutzer oder Leser, wenn Sie sich auf das Publikum beziehen.
• Wenn Sie Codebeispiele hinzufügen, stellen Sie sicher, dass sie korrekt formatiert und funktionsfähig sind.

Diese Richtlinien sind zwar nicht vollständig, sollten Ihnen aber den Einstieg erleichtern. Wenn Sie sich näher mit technischem Schreiben befassen möchten, sehen Sie sich den Google Technical Writing Course an.

Vielen Dank, dass Sie zur Dokumentation beitragen und Teil der Next.js-Community sind!