Leitfaden für Dokumentationsbeiträge

Willkommen zum 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 die 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 verwirrenden 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 Ihnen, den GitHub Open Source Guide zu lesen, 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 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

Änderungen lokal in der Vorschau anzeigen

VSCode hat einen eingebauten 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 Strg + Umschalt + 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.
• 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 in den Kommentaren Ihres PRs wissen, 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 in /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 dem Ordner- oder Dateinamen eine zweistellige Zahl (00-) voranstellen.

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

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.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 Strg + 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?

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 nicht mehr 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 oben in der Datei einen Metadatenblock, 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: Navigationstitel
source: app/building-your-application/optimizing/images
related:
  description: Siehe die API-Referenz für die Image-Komponente.
  links:
    - app/api-reference/components/image
version: experimental
---

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 zwischen ihnen geteilt werden.

Gemeinsame Seiten

Um Inhaltsduplizierung und das Risiko zu vermeiden, dass die Inhalte nicht mehr synchron sind, verwenden wir das Feld source, um Inhalte von einer Seite in eine andere zu ziehen. 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 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 angegebenen Quelle gezogen. */}

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

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 kann.

Wenn Sie beispielsweise zeigen möchten, 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">Über uns</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.

Gut zu wissen:

• Stellen Sie sicher, dass Sie die js-Erweiterung mit JSX-Code in JavaScript-Dateien verwenden.
• Beispiel: ```jsx filename="app/layout.js"

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">Über uns</Link>
}

Mehrere Zeilen: highlight={1,3}

import Link from 'next/link'

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

Zeilenbereich: highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">Über uns</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.

Erstellen Sie verwandte Links mit dem Feld related 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 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 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 minimalen 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.

Seitenarten

Dokumentationsseiten werden ebenfalls in zwei Kategorien unterteilt: Konzeptuelle Seiten und Referenzseiten.

• Konzeptuelle 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 sich konzeptuelle Seiten im Abschnitt Building Your Application.
• Referenzseiten dienen dazu, eine spezifische API zu erklären. Sie sind in der Regel kürzer und fokussierter. In der Next.js-Dokumentation finden sich Referenzseiten im Abschnitt API Reference.

Gut zu wissen: Je nach Seite, zu der Sie beitragen, müssen Sie möglicherweise einen anderen Stil und Tonfall verwenden. Konzeptuelle Seiten sind beispielsweise eher anleitend und verwenden das Wort Sie, um den Nutzer 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. Zögern Sie 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 wurde oder 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 Nutzer 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 geschlechtsneutrale Sprache. Verwenden Sie Entwickler, Nutzer oder Leser, wenn Sie sich an das Publikum richten.
• Wenn Sie Codebeispiele hinzufügen, stellen Sie sicher, dass sie korrekt formatiert und funktionsfähig sind.

Diese Richtlinien sind zwar nicht erschöpfend, sollten Ihnen aber den Einstieg erleichtern. Wenn Sie tiefer in das technische Schreiben einsteigen möchten, werfen Sie einen Blick auf den Google Technical Writing Course.

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