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

Добро пожаловать в руководство по вкладу в документацию 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!