refactor(docs): объединить setup/ и usage/ в прикладные разделы
Some checks failed
CI/CD Pipeline / docker (push) Has been cancelled
CI/CD Pipeline / deploy (push) Has been cancelled

- Директории setup/ и usage/ объединены в applied/ с подпапками для парных разделов
- Раздел «Работа с данными» вынесен на верхний уровень в data/
- Шаблоны генерации разделены на 4 файла: введение, настройка, создание, использование
- Обновлён сайдбар, CONTRIBUTING.md, MAP.md и все внутренние ссылки
- Обновлены требования и содержимое разделов (стили, шаблоны, SVG-спрайты)
This commit is contained in:
2026-04-29 11:25:58 +03:00
parent a6cd14585b
commit 9f1bc0cc32
34 changed files with 363 additions and 417 deletions

View File

@@ -37,22 +37,24 @@ docs/
│ ├── from-template.md
│ ├── manual.md
│ └── nextjs.md
── setup/ # Настройка: разовая настройка инструментов
├── aliases.md
├── biome.md
├── postcss.md
├── styles.md
├── svg-sprites.md
│ ├── templates.md
│ └── vscode.md
└── usage/ # Использование: повседневная работа
── applied/ # Прикладные разделы: настройка и использование
├── aliases.md
├── biome.md
├── postcss.md
├── vscode.md
├── styles/ # Стили: настройка + использование
│ ├── styles-setup.md
│ └── styles-usage.md
├── svg-sprites/ # SVG-спрайты: настройка + использование
│ ├── svg-sprites-setup.md
│ └── svg-sprites-usage.md
├── templates/ # Шаблоны генерации: настройка + использование
│ ├── templates-setup.md
│ └── templates-usage.md
├── project-structure.md
├── components.md
├── page-level.md
├── templates-generation.md
├── styles.md
├── images-sprites.md
├── svg-sprites.md
├── video.md
├── data/
├── stores.md
@@ -70,7 +72,7 @@ generate-llms.ts # Скрипт генерации llms.txt и R
### Добавление нового раздела
1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
`setup/` или `usage/`.
или `applied/`.
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
3. Запустить `npm run llms` для обновления `llms.txt` и README.
@@ -100,36 +102,27 @@ generate-llms.ts # Скрипт генерации llms.txt и R
Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
установка фреймворка. Раздел описывает порядок шагов на уровне всего
проекта; детали отдельных инструментов лежат в `setup/`.
проекта; детали отдельных инструментов лежат в `applied/`.
**Граница:** не дублирует разделы `setup/`. Ссылается на них как на
**Граница:** не дублирует разделы `applied/`. Ссылается на них как на
шаги в общем сценарии.
### Настройка (`setup/`)
### Прикладные разделы (`applied/`)
**Отвечает на вопрос:** «Как поставить и сконфигурировать инструмент
в новом проекте?»
**Отвечает на вопрос:** «Как поставить инструмент и как им пользоваться?»
Разовая установка отдельного инструмента или подсистемы (линтер,
CSS-процессор, генератор спрайтов, шаблоны). Каждый раздел —
самостоятельная подсистема. Выполняется один раз при заведении
проекта или при смене мажорной версии инструмента.
Прикладные разделы объединяют настройку и использование инструментов
и подсистем. Каждый раздел — самостоятельная предметная область.
Типичная структура `setup/`-страницы: требования → установка (шаги) →
конфиг → проверка.
Разделы делятся на два типа:
**Граница:** `setup/` — про настройку, `usage/` — про написание кода
с использованием уже настроенного инструмента.
1. **Только настройка** — разовая установка инструмента (линтер,
CSS-процессор, алиасы). Файл без суффикса: `biome.md`, `postcss.md`.
### Использование (`usage/`)
**Отвечает на вопрос:** «Как этим пользоваться в коде?»
Повседневная работа: как писать компоненты, стили, как получать данные,
как работать со сторами, локализацией, ассетами. Полное описание
конкретной области: структура файлов, правила, именование, типизация, примеры.
Шаблон страницы описан ниже в секции «Структура прикладного раздела».
2. **Настройка + использование** — область, требующая и установки,
и повседневных правил. Два файла с суффиксами: `styles-setup.md`
(настройка) и `styles-usage.md` (использование). В сайдбаре
оборачиваются в collapsed-группу.
**Граница:** прикладной раздел не дублирует базовые правила. Если правило
уже описано в `basics/` — прикладной раздел ссылается на него, но не
@@ -137,9 +130,9 @@ CSS-процессор, генератор спрайтов, шаблоны). К
## Структура прикладного раздела
Шаблон ниже относится к разделам `usage/` (повседневная работа).
Разделы `setup/` и `creating-project/` имеют другую структуру —
ориентированную на пошаговую установку (требования → установка →
Шаблон ниже относится к usage-страницам прикладных разделов (`applied/*-usage.md`).
Setup-страницы (`applied/*-setup.md`) и `creating-project/` имеют другую
структуру — ориентированную на пошаговую установку (требования → установка →
проверка).
Шаблон описывает все допустимые секции. Раздел включает только те,