update-docs

Программа для обновления документации Next.js

Помогает обновлять документацию Next.js на основе изменений в коде в активной ветке. Предназначено для сопровождающих, проверяющих PR на полноту документации.

Быстрый старт

1. Анализ изменений: запустите команду git diff canary...HEAD --stat , чтобы увидеть, какие файлы изменились
2. Определение затронутых документов: сопоставьте изменившиеся исходные файлы с путями в документации
3. Проверьте каждый документ: просмотрите обновления с подтверждением пользователя
4. Проверка: запустите pnpm lint для проверки форматирования
5. Фиксация: добавление изменений в документацию в стадию подготовки

Рабочий процесс: анализ изменений в коде

Шаг 1: Получить diff

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

Шаг 2: Определить изменения, относящиеся к документации

Ищите изменения в следующих областях:

Шаг 3: Сопоставить с файлами документации

Используйте сопоставление «код-документация» в references/CODE-TO-DOCS-MAPPING.md , чтобы найти соответствующие файлы документации.

Примеры сопоставлений:

• 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/

Рабочий процесс: обновление существующей документации

Шаг 1: Ознакомьтесь с текущей документацией

Перед внесением изменений ознакомьтесь с существующей документацией, чтобы понять:

• Текущую структуру и разделы
• Используемые поля в предваряющей части
• Используются ли / для контента, специфичного для маршрутизатора

Шаг 2: Определите, что необходимо обновить

К типичным обновлениям относятся:

• Новые свойства/параметры: добавьте их в таблицу свойств и создайте раздел с объяснением использования
• Изменение поведения: обновите описания и примеры
• Устаревшие функции: добавьте уведомления об устаревании и рекомендации по миграции
• Новые примеры: добавьте блоки кода в соответствии с соглашениями

Шаг 3: Применение обновлений с подтверждением

Для каждого изменения:

1. Покажите пользователю, что вы планируете изменить
2. Дождитесь подтверждения перед редактированием
3. Примените изменения
4. Перейдите к следующему изменению

Шаг 4: Проверьте наличие общего контента

Если в документе используется source шаблон поля (часто встречается в документах по маршрутизатору страниц), редактировать нужно исходный файл. Пример:

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

Редактируйте исходный файл маршрутизатора приложений, а не файл маршрутизатора страниц.

Шаг 5: Проверка изменений

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

Рабочий процесс: создание каркаса документации по новой функции

Используйте этот шаблон при добавлении документации для совершенно новых функций.

Шаг 1: Определите тип документации

Шаг 2: Создайте файл с правильным именем

• Используйте формат «kebab-case»: my-new-feature.mdx
• Добавьте числовой префикс, если порядок имеет значение: 05-my-new-feature.mdx
• Поместите файл в соответствующий каталог в зависимости от типа функции

Шаг 3: Используйте соответствующий шаблон

Шаблон справочника API:

---
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
\`\`\`

Шаблон руководства:

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

Шаг 4: Добавьте связанные ссылки

Обновите вступительную часть, указав ссылки на соответствующую документацию:

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

Соглашения по документации

См. references/DOC-CONVENTIONS.md для ознакомления с полными правилами форматирования.

Краткое руководство

Вступительная часть (обязательно):

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

Блоки кода:

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

Контент, относящийся к конкретному маршрутизатору:

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

Примечания:

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

Контрольный список для проверки

Перед фиксацией изменений в документации:

• В разделе «Frontmatter» есть title и description
• Блоки кода имеют filename атрибут
• В примерах TypeScript используется switcher с вариантом JS
• Таблицы пропсов имеют правильный формат
• Ссылки указывают на действительные пути
• pnpm lint проходит
• Изменения отображаются правильно (если доступен предварительный просмотр)

Ссылки

• references/DOC-CONVENTIONS.md - Полные правила оформления вступительной части и форматирования
• references/CODE-TO-DOCS-MAPPING.md - Сопоставление исходного кода с документацией