Руководство по вкладу в документацию

Добро пожаловать в руководство по вкладу в документацию Next.js! Мы рады вашему участию.

Эта страница содержит инструкции по редактированию документации Next.js. Наша цель — дать возможность каждому участнику сообщества вносить свой вклад и улучшать нашу документацию.

Почему стоит участвовать?

Работа над открытым исходным кодом никогда не заканчивается, как и документация. Участие в документации — это отличный способ для новичков начать работать с открытым исходным кодом, а для опытных разработчиков — уточнить сложные темы и поделиться знаниями с сообществом.

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

Как внести вклад

Контент документации можно найти в репозитории Next.js. Чтобы внести вклад, вы можете редактировать файлы напрямую на GitHub или клонировать репозиторий и редактировать файлы локально.

Рабочий процесс GitHub

Если вы новичок в GitHub, мы рекомендуем прочитать GitHub Open Source Guide, чтобы узнать, как форкнуть репозиторий, создать ветку и отправить pull request.

Полезно знать: Основной код документации находится в приватной кодовой базе, которая синхронизируется с публичным репозиторием Next.js. Это означает, что вы не можете предпросматривать документацию локально. Однако вы увидите свои изменения на nextjs.org после слияния pull request.

Написание MDX

Документация написана на MDX — формате markdown с поддержкой синтаксиса JSX. Это позволяет нам встраивать React-компоненты в документацию. Ознакомьтесь с GitHub Markdown Guide для быстрого обзора синтаксиса markdown.

VSCode

Предпросмотр изменений локально

VSCode имеет встроенный предпросмотрщик markdown, который можно использовать для локального просмотра изменений. Чтобы включить предпросмотрщик для файлов MDX, вам нужно добавить параметр конфигурации в настройки пользователя.

Откройте палитру команд (⌘ + ⇧ + P на Mac или Ctrl + Shift + P на Windows) и найдите Preferences: Open User Settings (JSON).

Затем добавьте следующую строку в файл settings.json:

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Затем снова откройте палитру команд и найдите Markdown: Preview File или Markdown: Open Preview to the Side. Это откроет окно предпросмотра, где вы сможете увидеть свои форматированные изменения.

Расширения

Мы также рекомендуем следующие расширения для пользователей VSCode:

• MDX: Intellisense и подсветка синтаксиса для MDX.
• Prettier: Форматирование файлов MDX при сохранении.

Процесс проверки

После отправки вашего вклада команды Next.js или Developer Experience проверят ваши изменения, предоставят обратную связь и объединят pull request, когда он будет готов.

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

Совет: Запустите pnpm prettier-fix, чтобы применить Prettier перед отправкой PR.

Структура файлов

Документация использует маршрутизацию на основе файловой системы. Каждая папка и файлы внутри /docs представляют сегмент маршрута. Эти сегменты используются для генерации URL-путей, навигации и хлебных крошек.

Структура файлов отражает навигацию, которую вы видите на сайте, и по умолчанию элементы навигации сортируются в алфавитном порядке. Однако мы можем изменить порядок элементов, добавив двузначный номер (00-) к имени папки или файла.

Например, в справочнике API функций страницы сортируются в алфавитном порядке, потому что это упрощает поиск конкретной функции для разработчиков:

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

Но в разделе маршрутизации файлы имеют префикс с двузначным номером, отсортированные в порядке, в котором разработчики должны изучать эти концепции:

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.mdx
└── ...

Чтобы быстро найти страницу, вы можете использовать ⌘ + P (Mac) или Ctrl + P (Windows) для открытия панели поиска в VSCode. Затем введите slug страницы, которую вы ищете. Например, defining-routes.

Почему не используется манифест?

Мы рассматривали использование файла манифеста (еще один популярный способ генерации навигации документации), но обнаружили, что манифест быстро рассинхронизируется с файлами. Маршрутизация на основе файловой системы заставляет нас думать о структуре документации и кажется более естественной для Next.js.

Метаданные

Каждая страница имеет блок метаданных в верхней части файла, разделенный тремя дефисами.

Обязательные поля

Следующие поля обязательны:

---
title: Заголовок страницы
description: Описание страницы
---

Хорошей практикой является ограничение заголовка страницы 2-3 словами (например, "Оптимизация изображений"), а описания — 1-2 предложениями (например, "Узнайте, как оптимизировать изображения в Next.js").

Необязательные поля

Следующие поля необязательны:

---
nav_title: Заголовок в навигации
source: app/building-your-application/optimizing/images
related:
  description: См. справочник API компонента Image.
  links:
    - app/api-reference/components/image
version: experimental
---

Документация App и Pages

Поскольку большинство функций в App Router и Pages Router совершенно разные, их документация для каждого из них хранится в отдельных разделах (02-app и 03-pages). Однако есть несколько функций, которые являются общими для них.

Общие страницы

Чтобы избежать дублирования контента и риска его рассинхронизации, мы используем поле source для включения контента с одной страницы на другую. Например, компонент <Link> ведет себя в основном одинаково в App и Pages. Вместо дублирования контента мы можем включить контент из app/.../link.mdx в pages/.../link.mdx:

---
title: <Link>
description: Справочник API компонента <Link>.
---

Этот справочник API поможет вам понять, как использовать свойства
и параметры конфигурации, доступные для компонента Link.

---
title: <Link>
description: Справочник API компонента <Link>.
source: app/api-reference/components/link
---

{/* НЕ РЕДАКТИРУЙТЕ ЭТУ СТРАНИЦУ. */}
{/* Контент этой страницы взят из указанного выше источника. */}

Таким образом, мы можем редактировать контент в одном месте, и он будет отражен в обоих разделах.

Общий контент

В общих страницах иногда может быть контент, который относится только к App Router или Pages Router. Например, компонент <Link> имеет свойство shallow, которое доступно только в Pages, но не в App.

Чтобы убедиться, что контент отображается только в правильном роутере, мы можем обернуть блоки контента в компоненты <AppOnly> или <PagesOnly>:

Этот контент является общим для App и Pages.

<PagesOnly>

Этот контент будет показан только в документации Pages.

</PagesOnly>

Этот контент является общим для App и Pages.

Скорее всего, вы будете использовать эти компоненты для примеров и блоков кода.

Блоки кода

Блоки кода должны содержать минимальный рабочий пример, который можно скопировать и вставить. Это означает, что код должен работать без дополнительной конфигурации.

Например, если вы показываете, как использовать компонент <Link>, вы должны включить оператор import и сам компонент <Link>.

import Link from 'next/link'

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

Всегда запускайте примеры локально перед их коммитом. Это гарантирует, что код актуален и работает.

Язык и имя файла

Блоки кода должны иметь заголовок, включающий язык и filename. Добавьте свойство filename, чтобы отобразить специальную иконку терминала, которая помогает пользователям понять, куда вводить команду. Например:

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

Большинство примеров в документации написаны на tsx и jsx, а некоторые на bash. Однако вы можете использовать любой поддерживаемый язык, вот полный список.

При написании блоков кода на JavaScript мы используем следующие комбинации языка и расширения.

Полезно знать:

• Убедитесь, что используете расширение js с кодом JSX в JavaScript-файлах.
• Например, ```jsx filename="app/layout.js"

Переключатель TS и JS

Добавьте переключатель языка для переключения между TypeScript и JavaScript. Блоки кода должны быть сначала на TypeScript с версией на JavaScript для удобства пользователей.

В настоящее время мы пишем примеры TS и JS один за другим и связываем их с помощью свойства switcher:

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

```

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

```

Полезно знать: Мы планируем автоматически компилировать TypeScript-сниппеты в JavaScript в будущем. А пока вы можете использовать transform.tools.

Подсветка строк

Строки кода могут быть подсвечены. Это полезно, когда вы хотите привлечь внимание к определенной части кода. Вы можете подсветить строки, передав номер в свойство highlight.

Одна строка: highlight={1}

import Link from 'next/link'

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

Несколько строк: highlight={1,3}

import Link from 'next/link'

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

Диапазон строк: highlight={1-5}

import Link from 'next/link'

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

Иконки

В документации доступны следующие иконки:

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

Вывод:

Мы не используем эмодзи в документации.

Примечания

Для информации, которая важна, но не критична, используйте примечания. Примечания — это хороший способ добавить информацию, не отвлекая пользователя от основного контента.

> **Полезно знать**: Это однострочное примечание.

> **Полезно знать**:
>
> - Мы также используем этот формат для многострочных примечаний.
> - Иногда есть несколько пунктов, которые стоит знать или учитывать.

Вывод:

Полезно знать: Это однострочное примечание.

Полезно знать:

• Мы также используем этот формат для многострочных примечаний.
• Иногда есть несколько пунктов, которые стоит знать или учитывать.

Связанные ссылки

Связанные ссылки направляют процесс обучения пользователя, добавляя ссылки на логические следующие шаги.

• Ссылки будут отображаться в виде карточек под основным контентом страницы.
• Ссылки будут автоматически генерироваться для страниц, у которых есть дочерние страницы.

Создавайте связанные ссылки с помощью поля related в метаданных страницы.

---
related:
  description: Узнайте, как быстро начать работу с вашим первым приложением.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

Вложенные поля

Диаграммы

Диаграммы — это отличный способ объяснить сложные концепции. Мы используем Figma для создания диаграмм, следуя руководству по дизайну Vercel.

Диаграммы в настоящее время находятся в папке /public в нашем приватном сайте Next.js. Если вы хотите обновить или добавить диаграмму, пожалуйста, создайте GitHub issue с вашими идеями.

Пользовательские компоненты и HTML

В документации доступны следующие React-компоненты: <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross /> и <Check />. Мы не разрешаем использование чистого HTML в документации, кроме тега <details>.

Если у вас есть идеи для новых компонентов, пожалуйста, создайте GitHub issue.

Руководство по стилю

Этот раздел содержит рекомендации по написанию документации для тех, кто новичок в техническом письме.

Шаблоны страниц

Хотя у нас нет строгого шаблона для страниц, в документации часто повторяются следующие разделы:

• Обзор: Первый абзац страницы должен объяснить пользователю, что это за функция и для чего она используется. За ним следует минимальный рабочий пример или справочник API.
• Соглашение: Если у функции есть соглашение, оно должно быть объяснено здесь.
• Примеры: Покажите, как можно использовать функцию в различных сценариях.
• Таблицы API: Страницы API должны иметь таблицу обзора внизу страницы со ссылками на разделы (по возможности).
• Следующие шаги (Связанные ссылки): Добавьте ссылки на связанные страницы, чтобы направить процесс обучения пользователя.

Не стесняйтесь добавлять эти разделы по мере необходимости.

Типы страниц

Страницы документации также делятся на две категории: концептуальные (Conceptual) и справочные (Reference).

• Концептуальные страницы используются для объяснения концепции или функциональности. Обычно они длиннее и содержат больше информации, чем справочные страницы. В документации Next.js концептуальные страницы находятся в разделе Building Your Application.
• Справочные страницы используются для объяснения конкретного API. Они обычно короче и более сфокусированы. В документации Next.js справочные страницы находятся в разделе API Reference.

Полезно знать: В зависимости от страницы, к которой вы вносите вклад, может потребоваться использовать разный стиль и тон изложения. Например, концептуальные страницы более инструктивны и используют слово вы для обращения к пользователю. Справочные страницы более технические, в них чаще используются императивные слова, такие как "создайте, обновите, примите", и слово вы обычно опускается.

Тон изложения

Вот несколько рекомендаций для поддержания единого стиля и тона в документации:

• Пишите четкие, лаконичные предложения. Избегайте отступлений от темы.
  • Если вы используете много запятых, подумайте о разбиении предложения на несколько или используйте список.
  • Заменяйте сложные слова более простыми. Например, используйте вместо утилизируйте.
• Будьте внимательны со словом это. Оно может быть неоднозначным и запутывающим, не бойтесь повторять подлежащее предложения, если это необходимо.
  • Например, Next.js использует React вместо Next.js использует это.
• Используйте активный залог вместо пассивного. Активные предложения легче читать.
  • Например, Next.js использует React вместо React используется Next.js. Если вы используете слова типа был и использовался, возможно, вы применяете пассивный залог.
• Избегайте слов типа легко, быстро, просто, всего лишь и т.д. Это субъективно и может демотивировать пользователей.
• Избегайте отрицательных слов типа не, нельзя, не будет и т.д. Это может демотивировать читателей.
  • Например, "Вы можете использовать компонент Link для создания ссылок между страницами" вместо "Не используйте тег <a> для создания ссылок между страницами".
• Пишите во втором лице (вы/ваш). Это делает текст более личным и вовлекающим.
• Используйте гендерно-нейтральный язык. Используйте разработчики, пользователи или читатели, когда обращаетесь к аудитории.
• Если добавляете примеры кода, убедитесь, что они правильно отформатированы и работают.

Хотя эти рекомендации не исчерпывающие, они помогут вам начать. Если вы хотите углубиться в техническое письмо, ознакомьтесь с Курсом технического письма от Google.

Спасибо за вклад в документацию и участие в сообществе Next.js!