docs: актуализировать структуру разделов и заблокировать пустые

- sidebar: «Данные» поднят сразу после «Страницы (App Router)»
- sidebar: пустые разделы (Изображения, Видео, Stores, Хуки, Шрифты,
  Локализация) оставлены без link с пометкой «· в разработке»
- index.md приведён к актуальной структуре sidebar (Workflow, Базовые
  правила, Установка и настройка, Использование)
- README.md перегенерирован

.vitepress/config.ts

@@ -56,11 +56,6 @@ const sidebar = [
       { text: 'Структура проекта', link: '/docs/usage/project-structure' },
       { text: 'Компоненты', link: '/docs/usage/components' },
       { text: 'Страницы (App Router)', link: '/docs/usage/page-level' },
-      { text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
-      { text: 'Стили', link: '/docs/usage/styles' },
-      { text: 'Изображения', link: '/docs/usage/images-sprites' },
-      { text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
-      { text: 'Видео', link: '/docs/usage/video' },
       {
         text: 'Данные',
         collapsed: true,
@@ -91,10 +86,17 @@ const sidebar = [
           { text: 'Realtime', link: '/docs/usage/data/realtime' },
         ],
       },
-      { text: 'Stores', link: '/docs/usage/stores' },
+      { text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
-      { text: 'Хуки', link: '/docs/usage/hooks' },
+      { text: 'Стили', link: '/docs/usage/styles' },
-      { text: 'Шрифты', link: '/docs/usage/fonts' },
+      // Неактивные разделы: страницы существуют, но пока пустые.
-      { text: 'Локализация', link: '/docs/usage/localization' },
+      // Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
+      { text: 'Изображения · в разработке' },
+      { text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
+      { text: 'Видео · в разработке' },
+      { text: 'Stores · в разработке' },
+      { text: 'Хуки · в разработке' },
+      { text: 'Шрифты · в разработке' },
+      { text: 'Локализация · в разработке' },
     ],
   },
 

README.md

@@ -2,34 +2,24 @@
 
 Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
 
+Сайт: https://nextjs-style-guide.gromlab.ru
+
 ## Использование
 
 **Для AI-агентов:**
 
-- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
+- [llms.txt](https://nextjs-style-guide.gromlab.ru/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
-- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
+- [llms-full.txt](https://nextjs-style-guide.gromlab.ru/llms-full.txt) — Вся документация одним файлом.
 
 **Для проекта:**
 
-- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
+- [nextjs-style-guide.zip](https://nextjs-style-guide.gromlab.ru/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
 
 ## Структура документации
 
 ### Workflow
 
-**Что делать и в каком порядке** — пошаговые инструкции.
+[Workflow](docs/docs/workflow.md) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию.
-
-| Раздел | Отвечает на вопрос |
-|--------|-------------------|
-| Начало работы | Что нужно знать перед началом разработки? |
-| Создание проекта | Как начать новый проект? |
-| Генерация кода | Какие модули должны генерироваться из шаблонов? |
-| Добавление страницы | Как добавить новую страницу в проект? |
-| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
-| Стилизация | Как стилизовать компоненты в проекте? |
-| Получение данных | Как получать данные с сервера? |
-| Управление состоянием | Как работать с состоянием? |
-| Локализация | Как добавлять переводы и подключать локализацию? |
 
 ### Базовые правила
 
@@ -38,32 +28,53 @@
 | Раздел | Отвечает на вопрос |
 |--------|-------------------|
 | Технологии и библиотеки | Какой стек используем? |
-| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
-| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
 | Именование | Как называть файлы, переменные, компоненты, хуки? |
+| Архитектура: Обзор | Что такое SLM и зачем она нужна? |
+| Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? |
+| Архитектура: Модули | Что такое модуль и как он устроен? |
+| Архитектура: Сегменты | Какие сегменты есть внутри модуля? |
+| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
 | Документирование | Как писать JSDoc: что документировать, а что нет? |
 | Типизация | Как типизировать: type vs interface, any/unknown? |
 
-### Прикладные разделы
+### Установка и настройка
 
-**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
+**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры.
+
+| Раздел | Отвечает на вопрос |
+|--------|-------------------|
+| Создание проекта: Из шаблона | Как начать проект из готового шаблона? |
+| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? |
+| Next.js | Как настроить Next.js под проект? |
+| Алиасы | Как настроить путевые алиасы импортов? |
+| Biome | Как настроить Biome (линтер и форматер)? |
+| Стили | Как подключить и настроить стили проекта? |
+| PostCSS | Какие плагины PostCSS нужны и как их настроить? |
+| SVG-спрайты | Как настроить генерацию SVG-спрайтов? |
+| Шаблоны генерации | Как подключить шаблоны для кодогенерации? |
+| VS Code | Как настроить редактор для проекта? |
+
+### Использование
+
+**Как это устроено и как этим пользоваться** — структура, примеры и правила для конкретных областей.
 
 | Раздел | Отвечает на вопрос |
 |--------|-------------------|
-| Настройка VS Code | Как настроить редактор для проекта? |
 | Структура проекта | Как организованы папки и файлы по SLM? |
 | Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
-| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
+| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
+| Данные: Введение | Как устроена работа с данными в проекте? |
+| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
+| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
+| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
+| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
+| Данные: Realtime | Как работать с realtime-каналами и сокетами? |
 | Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
 | Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
 | Изображения | _(не заполнен)_ |
-| SVG-спрайты | _(не заполнен)_ |
+| SVG-спрайты | Как использовать SVG-спрайты в коде? |
 | Видео | _(не заполнен)_ |
-| API | _(не заполнен)_ |
 | Stores | _(не заполнен)_ |
 | Хуки | _(не заполнен)_ |
 | Шрифты | _(не заполнен)_ |
 | Локализация | _(не заполнен)_ |
-
-
-

docs/docs/index.md

@@ -17,19 +17,7 @@
 
 ### Workflow
 
-**Что делать и в каком порядке** — пошаговые инструкции.
+[Workflow](/docs/workflow) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию.
-
-| Раздел | Отвечает на вопрос |
-|--------|-------------------|
-| Начало работы | Что нужно знать перед началом разработки? |
-| Создание проекта | Как начать новый проект? |
-| Генерация кода | Какие модули должны генерироваться из шаблонов? |
-| Добавление страницы | Как добавить новую страницу в проект? |
-| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
-| Стилизация | Как стилизовать компоненты в проекте? |
-| Получение данных | Как получать данные с сервера? |
-| Управление состоянием | Как работать с состоянием? |
-| Локализация | Как добавлять переводы и подключать локализацию? |
 
 ### Базовые правила
 
@@ -38,32 +26,53 @@
 | Раздел | Отвечает на вопрос |
 |--------|-------------------|
 | Технологии и библиотеки | Какой стек используем? |
-| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
-| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
 | Именование | Как называть файлы, переменные, компоненты, хуки? |
+| Архитектура: Обзор | Что такое SLM и зачем она нужна? |
+| Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? |
+| Архитектура: Модули | Что такое модуль и как он устроен? |
+| Архитектура: Сегменты | Какие сегменты есть внутри модуля? |
+| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
 | Документирование | Как писать JSDoc: что документировать, а что нет? |
 | Типизация | Как типизировать: type vs interface, any/unknown? |
 
-### Прикладные разделы
+### Установка и настройка
 
-**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
+**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры.
+
+| Раздел | Отвечает на вопрос |
+|--------|-------------------|
+| Создание проекта: Из шаблона | Как начать проект из готового шаблона? |
+| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? |
+| Next.js | Как настроить Next.js под проект? |
+| Алиасы | Как настроить путевые алиасы импортов? |
+| Biome | Как настроить Biome (линтер и форматер)? |
+| Стили | Как подключить и настроить стили проекта? |
+| PostCSS | Какие плагины PostCSS нужны и как их настроить? |
+| SVG-спрайты | Как настроить генерацию SVG-спрайтов? |
+| Шаблоны генерации | Как подключить шаблоны для кодогенерации? |
+| VS Code | Как настроить редактор для проекта? |
+
+### Использование
+
+**Как это устроено и как этим пользоваться** — структура, примеры и правила для конкретных областей.
 
 | Раздел | Отвечает на вопрос |
 |--------|-------------------|
-| Настройка VS Code | Как настроить редактор для проекта? |
 | Структура проекта | Как организованы папки и файлы по SLM? |
 | Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
-| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
+| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
+| Данные: Введение | Как устроена работа с данными в проекте? |
+| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
+| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
+| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
+| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
+| Данные: Realtime | Как работать с realtime-каналами и сокетами? |
 | Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
 | Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
 | Изображения | _(не заполнен)_ |
-| SVG-спрайты | _(не заполнен)_ |
+| SVG-спрайты | Как использовать SVG-спрайты в коде? |
 | Видео | _(не заполнен)_ |
-| API | _(не заполнен)_ |
 | Stores | _(не заполнен)_ |
 | Хуки | _(не заполнен)_ |
 | Шрифты | _(не заполнен)_ |
 | Локализация | _(не заполнен)_ |
-
-
-

generate-llms.ts

@@ -547,6 +547,29 @@ const buildSitemap = (): void => {
   console.log(`${PUBLIC_DIR}/sitemap.xml создан`);
 };
 
+/**
+ * Преобразовать абсолютные ссылки `index.md` в рабочие при открытии
+ * README в репозитории:
+ * - `/docs/foo` → относительный путь `docs/docs/foo.md`;
+ * - корневые ресурсы (`/llms.txt`, `/llms-full.txt`, `*.zip`, `/manifest.json`,
+ *   `/sitemap.xml`, `/robots.txt`) — генерируемые, в репозитории отсутствуют,
+ *   поэтому ссылки переписываются на абсолютный `SITE_URL`.
+ */
+const transformReadmeLinks = (content: string): string => {
+  const linkRe = /\]\((\/[^)\s]*)\)/g;
+  return content.replace(linkRe, (match, href: string) => {
+    const [pathPart, hash = ''] = href.split('#');
+    const hashPart = hash ? `#${hash}` : '';
+
+    if (pathPart.startsWith(DOC_PREFIX)) {
+      const rel = linkToArchiveRel(pathPart);
+      return `](docs/docs/${rel}${hashPart})`;
+    }
+
+    return `](${SITE_URL}${pathPart}${hashPart})`;
+  });
+};
+
 /** Скопировать `index.md` документации в корневой README без frontmatter. */
 const buildReadme = (): void => {
   const indexPath = 'docs/docs/index.md';
@@ -556,7 +579,15 @@ const buildReadme = (): void => {
   }
   const raw = fs.readFileSync(indexPath, 'utf8');
   const { body } = parseFrontmatter(raw);
-  fs.writeFileSync('README.md', body.trimStart(), 'utf8');
+  const transformed = transformReadmeLinks(body.trimStart());
+
+  // Порядок: H1 → описание (первый абзац) → ссылка на сайт.
+  const withSiteLink = transformed.replace(
+    /^(#\s[^\n]*\n\n[^\n]+\n)/,
+    `$1\nСайт: ${SITE_URL}\n`,
+  );
+
+  fs.writeFileSync('README.md', withSiteLink, 'utf8');
   console.log(`README.md обновлён из ${indexPath}`);
 };