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

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

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

Зачем вносить вклад?

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

Внося вклад в документацию 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.
• Grammarly: Проверка грамматики и орфографии.
• Prettier: Форматирование MDX-файлов при сохранении.

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

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

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

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

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

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

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

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

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

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

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.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
---

Документация 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">О нас</Link>
}

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

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

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

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

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

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

Переключатель 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">О нас</Link>
}

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

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">О нас</Link>
}

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

import Link from 'next/link'

export default function Page() {
  return <Link href="/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 должны иметь обзорную таблицу внизу страницы со ссылками на разделы (если возможно).
• Следующие шаги (Связанные ссылки): Добавьте ссылки на связанные страницы, чтобы направить процесс обучения пользователя.

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

Типы страниц

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

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

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

Стиль изложения

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

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

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

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