nextjs-style-guide/CONTRIBUTING.md

Правила работы над документацией

Мета-документ: как устроен проект, как писать и редактировать разделы.

О проекте

Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.

• Движок: VitePress
• Язык: русский
• Контент: docs/docs/

Команды

Команда	Что делает
npm run dev	Локальный сервер разработки
npm run build	Сборка статического сайта
npm run llms	Генерация llms.txt (карта документации для LLM) и README

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

docs/
├── index.md                     # Лендинг (URL `/`)
└── docs/                        # Контент документации (URL `/docs/...`)
    ├── index.md                 # Главная страница
    ├── workflow.md              # Подсказки
    ├── basics/                  # Базовые правила: каким должен быть код
    │   ├── tech-stack.md
    │   ├── architecture/
    │   ├── code-style.md
    │   ├── naming.md
    │   ├── documentation.md
    │   └── typing.md
    ├── creating-project/        # Создание проекта: как поднять новый проект
    │   ├── from-template.md
    │   ├── manual.md
    │   └── nextjs.md
    ├── data/                     # Работа с данными
    │   ├── index.md
    │   ├── realtime.md
    │   └── rest/
    └── applied/                  # Прикладные разделы: настройка и использование
        ├── project-structure.md
        ├── page-level.md
        ├── component.md
        ├── module.md
        ├── styles/               # Стили: настройка + использование
        │   ├── styles-setup.md
        │   └── styles-usage.md
        ├── svg-sprites/          # SVG-спрайты: введение + настройка + использование
        │   ├── svg-sprites-intro.md
        │   ├── svg-sprites-setup.md
        │   └── svg-sprites-usage.md
        ├── images.md
        ├── fonts.md
        ├── aliases.md
        ├── templates/            # Шаблоны генерации: введение + настройка + использование
        │   ├── templates-intro.md
        │   ├── templates-setup.md
        │   ├── templates-create.md
        │   └── templates-usage.md
        ├── biome.md
        ├── postcss.md
        ├── vscode.md
        ├── localization.md
        └── stores.md
.vitepress/
└── config.ts                    # Конфигурация VitePress, сайдбар
generate-llms.ts                 # Скрипт генерации llms.txt и README

Сгенерированные артефакты (docs/public/): llms.txt, llms-full.txt, nextjs-style-guide.zip, manifest.json, копии .md в docs/public/docs/.

Добавление нового раздела

1. Создать .md-файл в нужной папке: basics/, creating-project/, или applied/.
2. Добавить пункт в сайдбар — .vitepress/config.ts. Сайдбар — единственный источник порядка и группировки для llms.txt.
3. Запустить npm run llms для обновления llms.txt и README.

Типы разделов

Документация разделена на четыре группы. Каждая отвечает на свой вопрос и имеет свою природу — это влияет на содержимое и структуру страницы.

Базовые правила (basics/)

Отвечает на вопрос: «Каким должен быть любой код?»

Универсальные стандарты, не привязанные к конкретной области. Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать type vs interface.

Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.

Граница: если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.

Создание проекта (creating-project/)

Отвечает на вопрос: «Как поднять новый проект?»

Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая установка фреймворка. Раздел описывает порядок шагов на уровне всего проекта; детали отдельных инструментов лежат в applied/.

Граница: не дублирует разделы applied/. Ссылается на них как на шаги в общем сценарии.

Прикладные разделы (applied/)

Отвечает на вопрос: «Как поставить инструмент и как им пользоваться?»

Прикладные разделы объединяют настройку и использование инструментов и подсистем. Каждый раздел — самостоятельная предметная область.

Разделы делятся на два типа:

1. Только настройка — разовая установка инструмента (линтер, CSS-процессор, алиасы). Файл без суффикса: biome.md, postcss.md.

2. Настройка + использование — область, требующая и установки, и повседневных правил. Два файла с суффиксами: styles-setup.md (настройка) и styles-usage.md (использование). В сайдбаре оборачиваются в collapsed-группу.

Граница: прикладной раздел не дублирует базовые правила. Если правило уже описано в basics/ — прикладной раздел ссылается на него, но не повторяет.

Структура прикладного раздела

Шаблон ниже относится к usage-страницам прикладных разделов (applied/*-usage.md). Setup-страницы (applied/*-setup.md) и creating-project/ имеют другую структуру — ориентированную на пошаговую установку (требования → установка → проверка).

Шаблон описывает все допустимые секции. Раздел включает только те, которые для него релевантны — пустые секции не создаются.

# {Название}

{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
Правила оформления — секция «Заголовок и описание» ниже.}

## Что нужно знать

Неочевидная информация, которую читатель должен знать перед чтением раздела.
Если для раздела нет такой вводной — секция не создаётся.

## Структура

Файловая организация: какие файлы создавать и куда класть.
Обязательно — дерево файлов через code-block.

## Правила

Конкретные требования, специфичные для области. Делятся на две подсекции:

### Реализация

Как написан код внутри файла: синтаксис, паттерны, API.
Отвечает на вопрос: «Как писать код?»

Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.

### Организация

Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
Отвечает на вопрос: «Где что лежит и за что отвечает?»

Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.

Формат обеих подсекций — маркированный список.
Для неочевидных случаев — блоки «Хорошо / Плохо».
Если в области нет правил одной из категорий — подсекция не создаётся.

## Именование

Соглашения по именам, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Именование».

## Типизация

Правила типизации, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Типизация».

## Документирование

Что и как документировать в этой области.
Только то, что НЕ покрыто в базовом разделе «Документирование».

## Примеры

Полноценные примеры кода.
Каждый пример с путём к файлу и пояснениями.

Порядок секций

Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.

Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.

Секции-расширения базовых правил

«Именование», «Типизация», «Документирование» в прикладном разделе — это точки расширения базовых правил.

• В базовых описано общее: camelCase для переменных, type vs interface, формат JSDoc.
• В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).

Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.

Конвенции оформления

Frontmatter

Каждый .md-файл начинается с YAML frontmatter:

---
title: Название раздела
description: Описание раздела одним предложением.
---

• title совпадает с текстом h1-заголовка в файле.
• description совпадает с абзацем-описанием сразу под h1.

Подробнее о требованиях к самому заголовку и описанию — секция «Заголовок и описание» ниже.

Заголовок и описание

Каждая страница начинается с h1-заголовка и абзаца-описания сразу под ним. Эта пара — навигационный маркер: попадает в сайдбар, llms.txt, MAP.md архива и должна за секунду давать читателю или LLM понять, когда сюда нужно идти.

Структура заголовков

• Один h1 на файл, совпадает с title во frontmatter.
• Сразу после h1 — описание (одно-два предложения, см. ниже).
• Основные секции — h2.
• Подсекции внутри h2 — h3.
• h4 не используется.

Имя h1 (заголовок страницы)

• Называет предметную область, а не реализацию.
• Без имён пакетов, опций, конфигов и путей.
• Самодостаточен — читается без контекста сайдбара.
• Исключение: имя инструмента допустимо, если оно — единственное устойчивое имя самой области (PostCSS, Biome, VS Code).
• Если страница вложена в семантическую группу (Архитектура → Слои, Данные → REST → Серверные компоненты) и короткое имя теряет смысл при прямой ссылке — h1 поднимает имя родителя в заголовок: Слои SLM, Сегменты SLM. В сайдбаре допустимо оставить короткий вариант (Слои, Сегменты) — там путь группы виден через дерево.
• Подъём в заголовок применяется только когда читается грамматически естественно (Слои SLM, Автогенерация REST-клиента). Если получается натянутая конструкция (REST в серверных компонентах) — заголовок остаётся коротким, а контекст полностью переносится в описание. Заголовок и описание — пара: если один не несёт контекст, его обязательно несёт второй.

Хорошо: «Алиасы импортов», «Структура проекта», «SVG-спрайты», «Слои SLM», «Автогенерация REST-клиента».

Плохо: «Установка и настройка» (что устанавливаем?), «Использование» (что используем?), «Введение» (во что?), «Сегменты» (чего сегменты?), «REST в серверных компонентах» (грамматически натянуто — лучше короткий h1 + контекст в описании).

Описание

Описание — короткий ответ на вопрос «у меня задача X, мне сюда?». Не аннотация. Не оглавление.

Запреты:

• Не упоминать конкретные пакеты, библиотеки, инструменты (@gromlab/svg-sprites, Mantine, Zustand).
• Не упоминать конкретные файлы и пути (postcss.config.mjs, .templates/, biome.json).
• Не упоминать конкретные опции, ключи API, имена функций (baseUrl, cl(), useStore).
• Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе», «Здесь рассмотрено».
• Не использовать дежурные префиксы как шаблон («Правила работы с...», «Правила написания...») — само то, что раздел про правила, и так понятно из секции и заголовка.
• Не пересказывать содержимое перечислением подсекций («организация, реализация, делегирование, метаданные»).
• Не аргументировать пользу («обеспечит единообразие», «упростит поддержку»).

Требования:

• 1 предложение, обычно 5–12 слов.
• Звучит как ответ человека другу, а не как техспек.
• Описание читается самостоятельно, без контекста сайдбара.
• Если страница вложена в семантическую группу (например, Данные → REST → Клиенты → ...) и её заголовок без этой группы теряет смысл — описание явно содержит имя родительской области, чтобы читалось без сайдбара.

Подходящие формы:

• «Как X.»
• «Что такое X.»
• «Из чего состоит X.»
• «Установка X.»
• «Какие X есть и как ими пользоваться.»

Перечисление аспектов через двоеточие — только если без него читатель не сможет различить раздел от соседнего.

Тест навигации. Читатель видит описание — за секунду должен понять «мне сюда» или «нет, не сюда». Если приходится перечитывать — описание слишком длинное.

Тест на изменение. Если в разделе сменится пакет, переименуется файл или добавится правило — придётся ли править описание? Если да — оно слишком конкретное.

Хорошо:

Какие алиасы импортов есть в проекте и как ими пользоваться.

Установка и настройка линтера-форматтера в новом проекте.

Из чего состоит проект и где что лежит.

Получение REST-данных в серверных компонентах.

Плохо:

Раздел описывает, какие алиасы используются в проекте: их полный список,
где они объявлены и как ими пользоваться между модулями и внутри модуля.

Начинается с «Раздел описывает», пересказывает содержимое.

Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.

Упомянут конкретный файл, перечисление аспектов превратилось в оглавление.

Правила работы с React-компонентами: файловая структура,
типизация пропсов, документирование, реализация.

Дежурный префикс «Правила работы с...» плюс оглавление подсекций.

Примеры кода

• Блоки кода с указанием языка: ```tsx, ```css, ```bash, ```text.
• Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
• Дерево файлов — ```text с символами ├──, └──, │.

Блоки «Хорошо / Плохо»

Используются для контрастного сравнения правильного и неправильного подхода.

Формат:

**Хорошо:**

\`\`\`tsx
// правильный код
\`\`\`

**Плохо:**

\`\`\`tsx
// неправильный код
\`\`\`

Таблицы

Используются для структурированных перечислений: настройки, команды, соответствия. Формат — стандартный Markdown: | Ключ | Описание |.

Ссылки между разделами

Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.

Принципы

1. Не дублировать. Одна мысль живёт в одном месте. Остальные ссылаются.
2. Базовое vs прикладное. Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
3. Пустые секции не создавать. Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
4. Примеры обязательны. Прикладной раздел без примеров кода — незавершён.