docs: обновить структуру прикладных разделов
All checks were successful
CI/CD Pipeline / docker (push) Successful in 51s
CI/CD Pipeline / deploy (push) Successful in 7s

- перенесён раздел создания проекта в прикладные разделы

- переработаны разделы REST-клиента и получения данных

- удалена устаревшая категория работы с данными

- обновлён стандартный конфиг Biome

- добавлены правила для обязательного API baseUrl без fallback

- обновлены сайдбар, карта документации, README и ссылки
This commit is contained in:
2026-05-08 19:12:26 +03:00
parent eadc4627f7
commit 8231356d8d
27 changed files with 737 additions and 666 deletions

View File

@@ -33,19 +33,23 @@ docs/
│ ├── naming.md
│ ├── documentation.md
│ └── typing.md
├── creating-project/ # Создание проекта: как поднять новый проект
│ ├── from-template.md
│ ├── manual.md
│ └── nextjs.md
├── data/ # Работа с данными
│ ├── index.md
│ ├── realtime.md
│ └── rest/
└── applied/ # Прикладные разделы: настройка и использование
├── creating-project/ # Создание проекта: как поднять новый проект
│ ├── from-template.md
│ ├── manual.md
│ └── nextjs.md
├── project-structure.md
├── page-level.md
├── component.md
├── module.md
├── rest-client/ # REST-клиент: настройка клиента сервиса
│ ├── index.md
│ ├── usage.md
│ └── setup/
├── data-fetch/ # Получение данных: стратегии серверного и клиентского получения
│ ├── index.md
│ ├── server-await.md
│ └── client-get-hook.md
├── styles/ # Стили: настройка + использование
│ ├── styles-setup.md
│ └── styles-usage.md
@@ -76,15 +80,14 @@ generate-llms.ts # Скрипт генерации llms.txt и R
### Добавление нового раздела
1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
или `applied/`.
1. Создать `.md`-файл в нужной папке: `basics/` или `applied/`.
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
3. Запустить `npm run llms` для обновления `llms.txt` и README.
## Типы разделов
Документация разделена на четыре группы. Каждая отвечает на свой вопрос
Документация разделена на две основные группы. Каждая отвечает на свой вопрос
и имеет свою природу — это влияет на содержимое и структуру страницы.
### Базовые правила (`basics/`)
@@ -101,30 +104,25 @@ generate-llms.ts # Скрипт генерации llms.txt и R
**Граница:** если правило касается только одной области (только стили,
только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
### Создание проекта (`creating-project/`)
**Отвечает на вопрос:** «Как поднять новый проект?»
Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
установка фреймворка. Раздел описывает порядок шагов на уровне всего
проекта; детали отдельных инструментов лежат в `applied/`.
**Граница:** не дублирует разделы `applied/`. Ссылается на них как на
шаги в общем сценарии.
### Прикладные разделы (`applied/`)
**Отвечает на вопрос:** «Как поставить инструмент и как им пользоваться
**Отвечает на вопрос:** «Как решить практическую задачу в проекте
Прикладные разделы объединяют настройку и использование инструментов
Прикладные разделы объединяют создание проекта, настройку и использование инструментов
и подсистем. Каждый раздел — самостоятельная предметная область.
Разделы делятся на два типа:
`applied/creating-project/` отвечает на вопрос «Как поднять новый проект?» и описывает сценарии запуска нового проекта целиком: из шаблона, вручную, чистую установку фреймворка. Детали отдельных инструментов остаются в собственных прикладных разделах, а создание проекта ссылается на них как на шаги общего сценария.
1. **Только настройка** — разовая установка инструмента (линтер,
Разделы делятся на три типа:
1. **Создание проекта** — сценарии запуска проекта целиком. Живут в
`applied/creating-project/` и в сайдбаре оформляются как первая группа
прикладных разделов.
2. **Только настройка** — разовая установка инструмента (линтер,
CSS-процессор, алиасы). Файл без суффикса: `biome.md`, `postcss.md`.
2. **Настройка + использование** — область, требующая и установки,
3. **Настройка + использование** — область, требующая и установки,
и повседневных правил. Два файла с суффиксами: `styles-setup.md`
(настройка) и `styles-usage.md` (использование). В сайдбаре
оборачиваются в collapsed-группу.
@@ -136,7 +134,7 @@ generate-llms.ts # Скрипт генерации llms.txt и R
## Структура прикладного раздела
Шаблон ниже относится к usage-страницам прикладных разделов (`applied/*-usage.md`).
Setup-страницы (`applied/*-setup.md`) и `creating-project/` имеют другую
Setup-страницы (`applied/*-setup.md`) и `applied/creating-project/` имеют другую
структуру — ориентированную на пошаговую установку (требования → установка →
проверка).
@@ -260,7 +258,7 @@ description: Описание раздела одним предложением
- Исключение: имя инструмента допустимо, если оно — единственное
устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
- Если страница вложена в семантическую группу
(`Архитектура → Слои`, `Данные → REST → Серверные компоненты`)
(`Архитектура → Слои`, `Прикладные → REST-клиент → Использование`)
и короткое имя теряет смысл при прямой ссылке — `h1` поднимает
имя родителя в заголовок: `Слои SLM`, `Сегменты SLM`. В сайдбаре
допустимо оставить короткий вариант (`Слои`, `Сегменты`) — там
@@ -309,7 +307,7 @@ description: Описание раздела одним предложением
- Звучит как ответ человека другу, а не как техспек.
- Описание читается **самостоятельно**, без контекста сайдбара.
- Если страница вложена в семантическую группу
(например, `Данные → RESTКлиенты → ...`) и её заголовок
(например, `Прикладные → RESTлиент → Настройка → ...`) и её заголовок
без этой группы теряет смысл — описание явно содержит имя
родительской области, чтобы читалось без сайдбара.