docs: обновить структуру прикладных разделов
- перенесён раздел создания проекта в прикладные разделы - переработаны разделы REST-клиента и получения данных - удалена устаревшая категория работы с данными - обновлён стандартный конфиг Biome - добавлены правила для обязательного API baseUrl без fallback - обновлены сайдбар, карта документации, README и ссылки
This commit is contained in:
@@ -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-клиент → Настройка → ...`) и её заголовок
|
||||
без этой группы теряет смысл — описание явно содержит имя
|
||||
родительской области, чтобы читалось без сайдбара.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user