slm-design/CONTRIBUTING.md

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

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

О проекте

Сайт-документация архитектуры SLM Design с лендингом.

• Лендинг: React + Vite
• Документация: VitePress
• Язык: русский
• Документация: docs/architecture/

Команды

Команда	Что делает
npm run dev	Локальный сервер лендинга
npm run build	Сборка лендинга
npm run docs:dev	Локальный сервер документации
npm run docs:build	Сборка документации
npm run generate	Генерация артефактов (llms.txt, llms-full.txt, ARCHITECTURE.md, ZIP, README)

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

docs/
├── index.md                      # Страница навигации по документации
└── architecture/                 # Разделы архитектуры
    ├── index.md                  # Обзор SLM Design
    ├── layers.md                 # Слои
    ├── modules.md                # Модули
    └── segments.md               # Сегменты
.vitepress/
├── config.ts                     # Конфигурация VitePress, сайдбар
public/
├── llms.txt                      # Карта документации для LLM
├── llms-full.txt                 # Полная документация в одном файле
└── ARCHITECTURE.md               # Единый файл архитектуры
generate.ts                       # Скрипт генерации артефактов
src/                              # Исходники лендинга (React + Vite)

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

1. Создать .md-файл в docs/architecture/.
2. Добавить пункт в сайдбар — .vitepress/config.ts.
3. Добавить description в frontmatter файла — используется для llms.txt.
4. Запустить npm run generate для обновления артефактов.

Frontmatter

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

---
title: Название раздела
description: Краткое описание для llms.txt
---

• title — совпадает с h1-заголовком в файле.
• description — кратное описание содержимого страницы, используется при генерации llms.txt.

Структура страницы документации

Каждая страница начинается одинаково:

1. Заголовок (h1) — совпадает с title из frontmatter.
2. Описание раздела — 1–2 строки сразу после заголовка. Говорит, что это за раздел, какую информацию он описывает и что читатель в нём получит.
3. Определение (## Определение) — для справочных страниц, посвящённых одному термину. Короткая формулировка жирным: что это за сущность и какую роль она играет.
4. Контент — остальные h2-подразделы.

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

Заголовки

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

Примеры кода

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

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

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

**Хорошо:**

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

**Плохо:**

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

Таблицы

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

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

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

Принципы

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