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
    ├── workflow/                # Процессы разработки
    ├── basics/                  # Базовые правила
    │   ├── tech-stack.md
    │   ├── architecture/
    │   ├── code-style.md
    │   ├── naming.md
    │   ├── documentation.md
    │   └── typing.md
    ├── setup/                   # Установка: разовая настройка проекта
    │   ├── aliases.md
    │   ├── biome.md
    │   ├── postcss.md
    │   ├── svg-sprites.md
    │   └── vscode.md
    └── usage/                   # Использование: повседневная работа
        ├── project-structure.md
        ├── components.md
        ├── page-level.md
        ├── templates-generation.md
        ├── styles.md
        ├── images-sprites.md
        ├── svg-sprites.md
        ├── video.md
        ├── data/
        ├── stores.md
        ├── hooks.md
        ├── fonts.md
        └── localization.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-файл в нужной папке (docs/docs/basics/, docs/docs/setup/ или docs/docs/usage/).
2. Добавить пункт в сайдбар — .vitepress/config.ts. Сайдбар — единственный источник порядка и группировки для llms.txt.
3. Запустить npm run llms для обновления llms.txt и README.

Два типа документации

Базовые правила

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

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

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

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

Прикладные разделы

Отвечает на вопрос: «Как работать с X?»

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

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

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

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

# {Название}

Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.

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

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

## Структура

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

## Правила

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

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

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

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

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

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

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

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

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

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

## Типизация

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

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

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

## Примеры

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

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

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

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

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

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

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

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

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

Frontmatter

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

---
title: Название раздела
---

Значение title совпадает с текстом h1-заголовка в файле.

Заголовки

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

Вводный абзац

Абзац сразу после h1 отвечает на вопрос «о чём этот раздел?». Он попадает в llms.txt и README.md архива как краткое описание, поэтому должен быть плотным и без воды.

Правила:

• Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе», «Здесь рассмотрено», «В этом документе».
• Начинать с подлежащего — самой темы (Слои SLM:, Соглашения об именовании:).
• Двоеточие или тире для перечисления категорий и областей, а не конкретных значений из содержимого.
• Не дублировать содержимое: если внутри раздела 12 правил — не перечислять их во вводном абзаце.
• Не аргументировать («единые правила делают код предсказуемым»).
• 1–2 предложения.

Проверка: если при добавлении нового правила/инструмента/раздела вводный абзац придётся править — он слишком конкретный.

Хорошо:

Слои SLM: назначение, классификация, направление зависимостей, правила.

Базовый стек проекта по областям: UI, архитектура, данные, состояние,
локализация, тестирование, стили, генерация кода.

Плохо:

Раздел описывает слои SLM: что такое слой, какие бывают, как между
ними направлены зависимости и какие правила действуют на каждом.

Этот раздел описывает базовый стек технологий и библиотек, принятый в
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.

Примеры кода

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

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

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

Формат:

**Хорошо:**

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

**Плохо:**

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

Таблицы

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

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

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

Принципы

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