nextjs-style-guide/.vitepress/config.ts

import { defineConfig } from 'vitepress';

const sidebar = [
  {
    text: 'Главная',
    link: '/docs/',
  },
  {
    text: 'Подсказки',
    link: '/docs/workflow',
  },
  {
    text: 'Базовые правила',
    items: [
      { text: 'Технологии и библиотеки', link: '/docs/basics/tech-stack' },
      { text: 'Именование', link: '/docs/basics/naming' },
      {
        text: 'Архитектура',
        collapsed: true,
        items: [
          { text: 'Обзор', link: '/docs/basics/architecture/' },
          { text: 'Слои', link: '/docs/basics/architecture/layers' },
          { text: 'Модули', link: '/docs/basics/architecture/modules' },
          { text: 'Сегменты', link: '/docs/basics/architecture/segments' },
        ],
      },
      { text: 'Стиль кода', link: '/docs/basics/code-style' },
      { text: 'Документирование', link: '/docs/basics/documentation' },
      { text: 'Типизация', link: '/docs/basics/typing' },
    ],
  },
  {
    text: 'Создание проекта',
    items: [
      { text: 'Из шаблона', link: '/docs/creating-project/from-template' },
      { text: 'По гайду вручную', link: '/docs/creating-project/manual' },
      { text: 'Чистый Next.js', link: '/docs/creating-project/nextjs' },
    ],
  },
  {
    text: 'Работа с данными',
    // collapsed: true,
    items: [
      { text: 'Введение', link: '/docs/data/' },
      {
        text: 'REST',
        collapsed: true,
        items: [
          { text: 'Обзор', link: '/docs/data/rest/' },
          {
            text: 'Создание клиента',
            collapsed: true,
            items: [
              { text: 'Обзор', link: '/docs/data/rest/clients/' },
              { text: 'Автогенерация из OpenAPI', link: '/docs/data/rest/clients/auto' },
              { text: 'Ручное создание', link: '/docs/data/rest/clients/manual' },
              { text: 'GET-хуки REST-клиента', link: '/docs/data/rest/clients/hooks' },
            ],
          },
          {
            text: 'Использование',
            collapsed: true,
            items: [
              { text: 'Стратегии получения данных', link: '/docs/data/rest/strategies/' },
              { text: 'Серверный await', link: '/docs/data/rest/strategies/server-await' },
              { text: 'Параллельные серверные запросы', link: '/docs/data/rest/strategies/parallel-server-requests' },
              { text: 'Передача промиса ниже', link: '/docs/data/rest/strategies/pass-promise-down' },
              { text: 'Начальные данные для клиентских хуков', link: '/docs/data/rest/strategies/client-hooks-initial-data' },
              { text: 'Клиентский GET-хук', link: '/docs/data/rest/strategies/client-get-hook' },
              { text: 'Business-композиция', link: '/docs/data/rest/strategies/business-composition' },
            ],
          },
        ],
      },
      { text: 'Realtime', link: '/docs/data/realtime' },
    ],
  },
  {
    text: 'Прикладные разделы',
    items: [
      { text: 'Структура проекта', link: '/docs/applied/project-structure' },
      { text: 'Страницы', link: '/docs/applied/page-level' },
      { text: 'Компонент', link: '/docs/applied/component' },
      { text: 'Модуль', link: '/docs/applied/module' },
      {
        text: 'Стили',
        collapsed: true,
        items: [
          { text: 'Настройка', link: '/docs/applied/styles/styles-setup' },
          { text: 'Использование', link: '/docs/applied/styles/styles-usage' },
        ],
      },
      {
        text: 'SVG-спрайты',
        collapsed: true,
        items: [
          { text: 'Введение', link: '/docs/applied/svg-sprites/svg-sprites-intro' },
          { text: 'Настройка', link: '/docs/applied/svg-sprites/svg-sprites-setup' },
          { text: 'Использование', link: '/docs/applied/svg-sprites/svg-sprites-usage' },
        ],
      },
      { text: 'Изображения', link: '/docs/applied/images' },
      { text: 'Шрифты', link: '/docs/applied/fonts' },
      { text: 'Алиасы импортов', link: '/docs/applied/aliases' },
      {
        text: 'Шаблоны генерации',
        collapsed: true,
        items: [
          { text: 'Введение', link: '/docs/applied/templates/templates-intro' },
          { text: 'Настройка', link: '/docs/applied/templates/templates-setup' },
          { text: 'Создание шаблонов', link: '/docs/applied/templates/templates-create' },
          { text: 'Использование', link: '/docs/applied/templates/templates-usage' },
        ],
      },
      { text: 'Biome', link: '/docs/applied/biome' },
      { text: 'PostCSS', link: '/docs/applied/postcss' },
      { text: 'VS Code', link: '/docs/applied/vscode' },
      { text: 'Локализация', link: '/docs/applied/localization' },
      // Неактивные разделы: страницы существуют, но пока пустые.
      // Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
      { text: 'Stores · в разработке' }
    ],
  },
];

/**
 * Vite-плагин: отдаёт `.txt` и `.md` с явной кодировкой UTF-8.
 * Без этого браузер декодирует как ISO-8859-1 и кириллица ломается.
 */
const utf8TextPlugin = {
  name: 'utf8-text-files',
  configureServer(server: any) {
    server.middlewares.use((req: any, res: any, next: any) => {
      const url: string = req.url || '';
      if (url.endsWith('.txt') || url.endsWith('.md')) {
        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
      }
      next();
    });
  },
};

export default defineConfig({
  srcDir: 'docs',
  // `docs/public/` содержит сгенерированные `.md`-копии и `llms.txt` для LLM
  // (попадают в корень `dist/` как статика). Исключаем из сканирования
  // страниц, иначе VitePress рендерит их как HTML-страницы.
  //
  // `DEVELOP.md` и `MAP.md` — файлы архива (точка входа и карта).
  // Содержат относительные ссылки, на сайте им делать нечего —
  // эту роль выполняют сайдбар и `llms.txt`.
  srcExclude: ['public/**', '**/DEVELOP.md', '**/MAP.md'],
  lang: 'ru-RU',
  title: 'NextJS Style Guide',
  description: 'Стандарты разработки на Next.js + TypeScript с архитектурой SLM',

  // Чистые URL без `.html` — канон для индексации.
  // Серверная поддержка реализована в Caddyfile (try_files + редирект).
  cleanUrls: true,

  // Дублируем указатель на llms.txt в <head> — для агентов,
  // которые читают HTML, но не парсят полный DOM/href.
  head: [
    ['link', { rel: 'alternate', type: 'text/plain', href: '/llms.txt', title: 'llms.txt' }],
    ['link', { rel: 'alternate', type: 'text/plain', href: '/llms-full.txt', title: 'llms-full.txt' }],
  ],

  vite: {
    plugins: [utf8TextPlugin],
    define: {
      __BUILD_VERSION__: JSON.stringify(process.env.BUILD_VERSION || 'dev'),
    },
  },

  themeConfig: {
    sidebar,
    socialLinks: [
      { icon: 'github', link: 'https://gromlab.ru/docs/nextjs-style-guide' },
    ],
  },

  // Расширенный блок описания для llms.txt — даёт LLM полный
  // технический контекст: стек, методология, охват тем.
  // Используется в generate-llms.ts.
  llmsBlockquote:
    'Стандарты разработки frontend-приложений на Next.js (App Router) + TypeScript + React с архитектурой SLM (Scoped Layered Module Design — модульная архитектура со слоями ответственности, где каждый модуль содержит всё необходимое: компоненты, хуки, сторы, типы, стили).',
  llmsContext:
    'Стек: React, TypeScript, Next.js App Router, Mantine UI, SWR, Zustand, i18next, PostCSS Modules, Vitest, clsx.\n\nДокументация покрывает архитектуру SLM (слои, модули, сегменты, направление зависимостей, публичный API), правила оформления кода (именование, форматирование, импорты, типизация, JSDoc), реализацию компонентов и хуков, работу с App Router, кодогенерацию из шаблонов, стилизацию (Mobile First, токены), работу с API и сокетами, управление состоянием через Zustand, локализацию, ассеты (шрифты, изображения, SVG-спрайты) и настройку VS Code.',
} as any);