update-docs

Next.js-Dokumentations-Updater

Führt Sie durch die Aktualisierung der Next.js-Dokumentation auf der Grundlage von Codeänderungen im aktiven Zweig. Konzipiert für Betreuer, die Pull-Requests auf Vollständigkeit der Dokumentation prüfen.

Schnellstart

1. Änderungen analysieren: Führen Sie git diff canary...HEAD --stat aus, um zu sehen, welche Dateien sich geändert haben
2. Betroffene Dokumente identifizieren: Ordnen Sie geänderte Quelldateien den Dokumentationspfaden zu
3. Jedes Dokument überprüfen: Gehen Sie die Aktualisierungen Schritt für Schritt durch und lassen Sie den Benutzer diese bestätigen
4. Validieren: Führen Sie pnpm lint , um die Formatierung zu überprüfen
5. Commit: Dokumentationsänderungen bereitstellen

Workflow: Codeänderungen analysieren

Schritt 1: Den Diff abrufen

# See all changed files on this branch
git diff canary...HEAD --stat# See changes in specific areas
git diff canary...HEAD -- packages/next/src/

Schritt 2: Dokumentationsrelevante Änderungen identifizieren

Suchen Sie nach Änderungen in diesen Bereichen:

Schritt 3: Zuordnung zu Dokumentationsdateien

Verwenden Sie die Code-zu-Dokumente-Zuordnung in references/CODE-TO-DOCS-MAPPING.md , um die entsprechenden Dokumentationsdateien zu finden.

Beispielzuordnungen:

• src/client/components/image.tsx → docs/01-app/03-api-reference/02-components/image.mdx
• src/server/config-shared.ts → docs/01-app/03-api-reference/05-config/

Workflow: Vorhandene Dokumentation aktualisieren

Schritt 1: Lesen Sie die aktuelle Dokumentation

Bevor Sie Änderungen vornehmen, lesen Sie die vorhandene Dokumentation, um Folgendes zu verstehen:

• die aktuelle Struktur und die Abschnitte
• Verwendete Frontmatter-Felder
• Ob / für router-spezifische Inhalte verwendet wird

Schritt 2: Ermitteln Sie, was aktualisiert werden muss

Häufige Aktualisierungen umfassen:

• Neue Props/Optionen: In die Props-Tabelle aufnehmen und einen Abschnitt erstellen, in dem die Verwendung erläutert wird
• Geändertes Verhalten: Beschreibungen und Beispiele aktualisieren
• Veraltete Funktionen: Fügen Sie Veraltungshinweise und Migrationsanleitungen hinzu
• Neue Beispiele: Fügen Sie Code-Blöcke gemäß den Konventionen hinzu

Schritt 3: Aktualisierungen mit Bestätigung übernehmen

Für jede Änderung:

1. Zeigen Sie dem Benutzer, was Sie ändern möchten
2. Warten Sie auf die Bestätigung, bevor Sie die Bearbeitung vornehmen
3. Die Änderung übernehmen
4. Fahren Sie mit der nächsten Änderung fort

Schritt 4: Auf gemeinsam genutzte Inhalte prüfen

Wenn das Dokument das source Feldmuster verwendet (üblich bei „Pages Router“-Dokumenten), ist die Quelldatei diejenige, die bearbeitet werden muss. Beispiel:

# docs/02-pages/... file with shared content
---
source: app/building-your-application/optimizing/images
---

Bearbeiten Sie die „App Router“-Quelldatei, nicht die „Pages Router“-Datei.

Schritt 5: Änderungen validieren

pnpm lint          # Check formatting
pnpm prettier-fix  # Auto-fix formatting issues

Workflow: Dokumentation für neue Funktionen erstellen

Verwenden Sie diesen Schritt, wenn Sie Dokumentation für völlig neue Funktionen hinzufügen.

Schritt 1: Dokumenttyp festlegen

Schritt 2: Erstellen Sie die Datei mit der richtigen Namenskonvention

• Verwenden Sie „Kebab-Case“: my-new-feature.mdx
• Fügen Sie ein numerisches Präfix hinzu, wenn die Reihenfolge eine Rolle spielt: 05-my-new-feature.mdx
• Speichern Sie die Datei je nach Funktionstyp im richtigen Verzeichnis

Schritt 3: Verwenden Sie die passende Vorlage

API-Referenzvorlage:

---
title: Feature Name
description: Brief description of what this feature does.
---{/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}Brief introduction to the feature.## Reference### Props
| Prop                    | Example            | Type   | Status   |
| ----------------------- | ------------------ | ------ | -------- |
| [`propName`](#propname) | `propName="value"` | String | Required |
#### `propName`Description of the prop.\`\`\`tsx filename="app/example.tsx" switcher
// TypeScript example
\`\`\`\`\`\`jsx filename="app/example.js" switcher
// JavaScript example
\`\`\`

Anleitungsvorlage:

---
title: How to do X in Next.js
nav_title: X
description: Learn how to implement X in your Next.js application.
---Introduction explaining why this guide is useful.## PrerequisitesWhat the reader needs to know before starting.## Step 1: First StepExplanation and code example.\`\`\`tsx filename="app/example.tsx" switcher
// Code example
\`\`\`## Step 2: Second StepContinue with more steps...## Next StepsRelated topics to explore.

Schritt 4: Fügen Sie relevante Links hinzu

Aktualisieren Sie den Frontmatter mit zugehöriger Dokumentation:

related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/functions/related-function
    - app/guides/related-guide

Konventionen für die Dokumentation

Siehe references/DOC-CONVENTIONS.md für die vollständigen Formatierungsregeln.

Kurzanleitung

Frontmatter (erforderlich):

---
title: Page Title (2-3 words)
description: One or two sentences describing the page.
---

Code-Blöcke:

\`\`\`tsx filename="app/page.tsx" switcher
// TypeScript first
\`\`\`\`\`\`jsx filename="app/page.js" switcher
// JavaScript second
\`\`\`

Router-spezifischer Inhalt:

Content only for App Router docs.Content only for Pages Router docs.

Hinweise:

> **Good to know**: Single line note.> **Good to know**:
>
> - Multi-line note point 1
> - Multi-line note point 2

Checkliste zur Validierung

Vor dem Commit von Dokumentationsänderungen:

• Der Frontmatter enthält title und description
• Code-Blöcke haben das filename Attribut
• TypeScript-Beispiele verwenden switcher mit der JS-Variante
• Props-Tabellen sind korrekt formatiert
• Verwandte Links verweisen auf gültige Pfade
• pnpm lint besteht
• Änderungen werden korrekt gerendert (sofern eine Vorschau verfügbar ist)

Referenzen

• references/DOC-CONVENTIONS.md - Vollständige Frontmatter- und Formatierungsregeln
• references/CODE-TO-DOCS-MAPPING.md - Zuordnung von Quellcode zur Dokumentation