refactor(docs): объединить setup/ и usage/ в прикладные разделы
- Директории setup/ и usage/ объединены в applied/ с подпапками для парных разделов - Раздел «Работа с данными» вынесен на верхний уровень в data/ - Шаблоны генерации разделены на 4 файла: введение, настройка, создание, использование - Обновлён сайдбар, CONTRIBUTING.md, MAP.md и все внутренние ссылки - Обновлены требования и содержимое разделов (стили, шаблоны, SVG-спрайты)
This commit is contained in:
@@ -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/` имеют другую
|
||||
структуру — ориентированную на пошаговую установку (требования → установка →
|
||||
проверка).
|
||||
|
||||
Шаблон описывает все допустимые секции. Раздел включает только те,
|
||||
|
||||
Reference in New Issue
Block a user