Dokumentations-Beitragsleitfaden

Willkommen im Next.js Dokumentations-Beitragsleitfaden! Wir freuen uns, dass Sie hier sind.

Diese Seite enthält Anweisungen, wie Sie die Next.js-Dokumentation bearbeiten können. Unser Ziel ist es sicherzustellen, dass sich jedes Mitglied der Community ermutigt und befähigt fühlt, zur Verbesserung unserer Dokumentation beizutragen.

Warum beitragen?

Open-Source-Arbeit ist nie fertig, und auch die Dokumentation nicht. Der Beitrag zur Dokumentation ist eine gute Möglichkeit für Anfänger, sich an Open-Source zu beteiligen 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 verwirrenden Abschnitt oder erkannt haben, dass ein bestimmtes Thema fehlt - Ihre Beiträge sind willkommen und werden geschätzt.

Wie man beiträgt

Der Dokumentationsinhalt befindet sich im Next.js-Repository. Um beizutragen, können Sie die Dateien direkt auf GitHub bearbeiten oder das Repository klonen und die Dateien lokal bearbeiten.

GitHub-Arbeitsablauf

Wenn Sie neu bei GitHub sind, empfehlen wir Ihnen, die GitHub Open Source Anleitung zu lesen, um zu lernen, wie man ein Repository forkt, einen Branch erstellt und einen Pull-Request einreicht.

Hinweis: Der zugrunde liegende Dokumentationscode lebt in einer privaten Codebasis, die mit dem Next.js öffentlichen Repository synchronisiert wird. Das bedeutet, dass Sie die Dokumentation nicht lokal vorschauern können. Ihre Änderungen werden jedoch nach dem Mergen eines Pull-Requests auf nextjs.org sichtbar sein.

MDX schreiben

Die Dokumentation wird in MDX geschrieben, einem Markdown-Format, das JSX-Syntax unterstützt. Dies ermöglicht uns, React-Komponenten in die Dokumentation einzubetten. Werfen Sie einen Blick auf den GitHub Markdown-Leitfaden für einen kurzen Überblick über die Markdown-Syntax.

VSCode

Änderungen lokal vorschauern

VSCode verfügt über einen integrierten Markdown-Previewer, den Sie verwenden können, um Ihre Bearbeitungen lokal zu sehen. Um den Previewer für MDX-Dateien zu aktivieren, müssen Sie eine Konfigurationsoption in 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 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. Dies öffnet ein Vorschaufenster, in dem Sie Ihre formatierten Änderungen sehen können.

Erweiterungen

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

• MDX: Intellisense und Syntaxhervorhebung für MDX.
• Prettier: Formatiere MDX-Dateien beim Speichern.

Überprüfungsprozess

Sobald Sie Ihren Beitrag eingereicht haben, werden das Next.js- oder Developer Experience-Team Ihre Änderungen überprüfen, Feedback geben und den Pull-Request zusammenführen, wenn er bereit ist.

Bitte lassen Sie uns in den Kommentaren Ihres Pull-Requests wissen, falls 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 Pull-Requests auszuführen.

Dateistruktur

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

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

Zum Beispiel sind in der Funktionen-API-Referenz die Seiten alphabetisch sortiert, da dies es Entwicklern erleichtert, eine bestimmte Funktion zu finden:

04-functions
├── cacheTag.mdx
├── connection.mdx
├── cookies.mdx
└── ...

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

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.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 Seite ein, nach der Sie suchen. Z.B. defining-routes

Warum keine Manifest-Datei?

Wir haben eine Manifest-Datei in Erwägung gezogen (eine weitere beliebte Methode zum Generieren der Dokumentationsnavigation), aber wir haben festgestellt, dass eine Manifest-Datei schnell aus Sync mit den Dateien geraten würde. Das Dateisystem-Routing zwingt uns, über die Struktur der Dokumentation nachzudenken und fühlt sich natürlicher für Next.js an.

Metadaten

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

Erforderliche Felder

Die folgenden Felder sind erforderlich:

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

Es ist empfehlenswert, den Seitentitel auf 2-3 Wörter zu begrenzen (z.B. Bilder optimieren) und die Beschreibung auf 1-2 Sätze (z.B. Lernen Sie, wie Sie Bilder in Next.js optimieren).

Optionale Felder

Die folgenden Felder sind optional:

---
nav_title: Navigationsposttitel
source: app/building-your-application/optimizing/images
related:
  description: Weitere Informationen zur Bild-Komponenten-API.
  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) getrennt gehalten. Es gibt jedoch einige Funktionen, die beiden gemeinsam sind.

Gemeinsame Seiten

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

---
title: <Link>
description: API-Referenz für die Link-Komponente.
---
 
Diese API-Referenz wird Ihnen helfen zu verstehen, wie Sie die verfügbaren
Props und Konfigurationsoptionen für die Link-Komponente verwenden können.

---
title: <Link>
description: API-Referenz für die Link-Komponente.
source: app/api-reference/components/link
---
 
{/* BEARBEITEN SIE DIESE SEITE NICHT. */}
{/* Der Inhalt dieser Seite wird aus der oben genannten Quelle gezogen. */}

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

Gemeinsamer Inhalt

In gemeinsamen Seiten gibt es manchmal Inhalte, die spezifisch für den App Router oder Pages Router sind. Zum Beispiel hat die <Link> Komponente eine shallow Eigenschaft, 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 einschließen:

Dieser Inhalt ist zwischen App und Pages gemeinsam.
 
<PagesOnly>
 
Dieser Inhalt wird nur in den Pages-Docs angezeigt.
 
</PagesOnly>
 
Dieser Inhalt ist zwischen App und Pages gemeinsam.

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 man die <Link> Komponente verwendet, sollten Sie die import-Anweisung und die <Link> Komponente selbst einschließen.

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. Dies stellt sicher, dass der Code aktuell und funktionsfähig ist.

Sprache und Dateiname

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

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

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

Beim Schreiben von JavaScript-Codeblöcken verwenden wir die folgenden Sprach- und Erweiterungskombinationen.

TS und JS Switcher

Fügen Sie einen Sprachumschalter hinzu, um zwischen TypeScript und JavaScript zu wechseln. Codeblöcke sollten zunächst in TypeScript sein, mit einer JavaScript-Version, um Benutzern entgegenzukommen.

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

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

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

Hervorheben von Zeilen

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 Nummer an die highlight-Eigenschaft ü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 stehen in den Docs zur Verfügung:

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

Ausgabe:

Wir verwenden keine Emojis in den Docs.

Notizen

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

> **Hinweis**: Dies ist eine einzeilige Notiz.
 
> **Hinweis**:
>
> - Wir verwenden auch dieses Format für mehrzeilige Notizen.
> - Es gibt manchmal mehrere Dinge, die man wissen oder im Hinterkopf behalten sollte.

Ausgabe:

Hinweis: Dies ist eine einzeilige Notiz.

Hinweis:

• Wir verwenden auch dieses Format für mehrzeilige Notizen.
• Es gibt manchmal mehrere Dinge, die man wissen oder im Hinterkopf behalten sollte.

Verwandte Links

Verwandte Links leiten den Lernpfad 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. Zum Beispiel hat der Abschnitt Optimierung Links zu allen seinen Unterseiten.

Erstellen Sie verwandte Links mithilfe des related-Feldes 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 hervorragende Möglichkeit, komplexe Konzepte zu erklären. Wir verwenden Figma, um Diagramme zu erstellen und folgen dabei dem Vercel-Designleitfaden.

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

Benutzerdefinierte Komponenten und HTML

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

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

Styleguide

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

Seitenvorlagen

Obwohl wir keine strikte Vorlage für Seiten haben, gibt es Seitenabschnitte, die über die Docs hinweg wiederholt werden:

• Übersicht: Der erste Absatz einer Seite sollte dem Benutzer erklären, 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 genutzt werden kann.
• API-Tabellen: API-Seiten sollten am Ende der Seite eine Übersichtstabelle mit Sprunglinks haben (wenn möglich).
• Nächste Schritte (Verwandte Links): Fügen Sie Links zu verwandten Seiten hinzu, um den Lernpfad des Benutzers zu leiten.

Fügen Sie diese Abschnitte nach Bedarf hinzu.

Seitentypen

Dokumentationsseiten sind in zwei Kategorien unterteilt: Konzeptionell und Referenz.

• Konzeptionelle Seiten werden verwendet, um 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 befinden sich konzeptionelle Seiten im Abschnitt Anwendung erstellen.
• Referenz-Seiten werden verwendet, um eine spezifische API zu erklären. Sie sind in der Regel kürzer und fokussierter. In der Next.js-Dokumentation befinden sich Referenzseiten im Abschnitt API-Referenz.

Hinweis: Je nach Seite, zu der Sie beitragen, müssen Sie möglicherweise einen anderen Ton und Stil verwenden. Beispielsweise sind konzeptionelle Seiten lehrorientierter und verwenden das Wort du, um den Benutzer anzusprechen. Referenzseiten sind technischer, sie verwenden mehr imperative Wörter wie „erstellen, aktualisieren, akzeptieren" und neigen dazu, das Wort du wegzulassen.

Sprachstil

Hier sind einige Richtlinien zur Wahrung eines konsistenten Stils und Tons in der Dokumentation:

• Schreiben Sie klare, prägnante Sätze. Vermeiden Sie Abschweifungen.
  • Wenn Sie viele Kommata verwenden, erwägen Sie, den Satz in mehrere Sätze zu unterteilen oder eine Liste zu 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, zögern Sie nicht, das Satzsubjekt bei Unklarheiten zu wiederholen.
  • Zum Beispiel Next.js verwendet React statt Next.js verwendet dies.
• Verwenden Sie eine aktive Stimme statt einer passiven. 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, benutzen Sie möglicherweise eine passive Stimme.
• Vermeiden Sie Wörter wie einfach, schnell, simpel, nur usw. Dies ist subjektiv und kann Benutzer entmutigen.
• Vermeiden Sie negative Wörter wie nicht, kann nicht, wird nicht usw. Dies kann Leser entmutigen.
  • Zum Beispiel „Sie können die Link-Komponente verwenden, um Links zwischen Seiten zu erstellen" statt „Verwenden Sie die <a>-Markierung nicht, um Links zwischen Seiten zu erstellen".
• Schreiben Sie in der zweiten Person (du/dein). Dies 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 ordnungsgemäß formatiert und funktionsfähig sind.

Während diese Richtlinien nicht erschöpfend sind, sollten sie Ihnen helfen, zu beginnen. Wenn Sie sich näher mit technischem Schreiben beschäftigen möchten, sehen Sie sich den Google-Lehrgang zum technischen Schreiben an.

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