Dokumentations-Beitragsleitfaden

Willkommen zum Next.js Dokumentations-Beitragsleitfaden! 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 nie abgeschlossen, und das gilt auch für Dokumentation. Beiträge zur Dokumentation sind 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 man beiträgt

Die Dokumentationsinhalte finden Sie im Next.js-Repo. Um beizutragen, 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 die Lektüre des GitHub Open Source Guide, um zu lernen, wie man ein Repository forkt, einen Branch erstellt und einen Pull Request einreicht.

Gut zu wissen: Der zugrunde liegende Dokumentationscode befindet sich in einer privaten Codebasis, die mit dem öffentlichen Next.js-Repo synchronisiert wird. Das bedeutet, dass Sie die Dokumentation nicht lokal in der Vorschau anzeigen können. Sie sehen Ihre Änderungen jedoch auf nextjs.org, 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 eine schnelle Übersicht über die Markdown-Syntax.

VSCode

Änderungen lokal in der Vorschau anzeigen

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: MDX-Dateien beim Speichern formatieren.

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 bereit ist.

Bitte lassen Sie uns wissen, wenn Sie Fragen haben oder weitere Hilfe in den Kommentaren Ihres PRs 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 stellt ein Routensegment dar. 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 dem Ordner- oder Dateinamen eine zweistellige Zahl (00-) 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-Abschnitt 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 erwogen, eine Manifest-Datei (eine andere beliebte Methode zur Generierung der Dokumentationsnavigation) zu verwenden, aber wir haben festgestellt, dass ein Manifest schnell mit den Dateien desynchronisiert werden würde. 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 (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") zu beschränken.

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) aufbewahrt. 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 ziehen. Beispielsweise verhält sich die <Link>-Komponente in App und Pages weitgehend gleich. Anstatt den Inhalt zu duplizieren, können wir den Inhalt von app/.../link.mdx in pages/.../link.mdx ziehen:

---
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 aus der oben genannten Quelle gezogen. */}

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

Gemeinsame Inhalte

In gemeinsamen Seiten gibt es manchmal Inhalte, 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 minimales 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, sich zu orientieren, 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-Umschalter

Fügen Sie einen Sprachumschalter 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 hintereinander 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.
> - Es gibt manchmal 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.
• Es gibt manchmal 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 Abschnitt Optimierung 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 nach dem Vercel-Design-Leitfaden zu erstellen.

Die Diagramme befinden sich derzeit im /public-Ordner unserer privaten Next.js-Website. 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 keine strikte Vorlage 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 das Feature ist und wofür es verwendet wird. Gefolgt von einem minimalen funktionierenden Beispiel oder seiner API-Referenz.
• Konvention: Wenn das Feature eine Konvention hat, sollte diese hier erklärt werden.
• Beispiele: Zeigen Sie, wie das Feature mit verschiedenen Anwendungsfällen verwendet werden kann.
• API-Tabellen: API-Seiten sollten eine Übersichtstabelle am Ende der Seite mit Sprunglinks zu Abschnitten haben (wenn möglich).
• 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.

Seitenarten

Dokumentationsseiten werden 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 bestimmte 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 nachdem, zu welcher Seite 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 eher 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 eine aktive statt einer passiven Stimme. 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 wurde und von verwenden, verwenden Sie möglicherweise eine passive Stimme.
• 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 für Leser entmutigend sein.
  • 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 eine 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 tiefer in das technische Schreiben einsteigen möchten, lesen Sie den Google Technical Writing Course (Google-Kurs zum technischen Schreiben).

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