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

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

## О проекте

Сайт-документация архитектуры 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:

```yaml
---
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 ` с символами `├──`, `└──`, `│`.

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

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

```markdown
**Хорошо:**

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

**Плохо:**

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

### Таблицы

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

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

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

## Принципы

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