docs: добавить описание проекта

- добавлено назначение хаба документаций - описаны структура проекта и основные команды - задокументированы LLM-артефакты, Caddy, Docker и CI/CD
2026-05-13 10:15:33 +03:00
parent 2811915128
commit a9e18f9269
1 changed files with 98 additions and 61 deletions
--- a/README.md
+++ b/README.md
@@ -1,73 +1,110 @@
-# React + TypeScript + Vite
+# Документация

-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Единое пространство для идей, черновиков и первых версий документаций, которые ещё формируются и постепенно становятся самостоятельными материалами.

-Currently, two official plugins are available:
+Проект собирает рабочие документации, стандарты и LLM-артефакты в одном месте, чтобы не создавать отдельное пространство для каждого материала на ранней стадии.

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+## Что внутри

-## React Compiler
+- React/Vite-лендинг со списком документаций.
+- VitePress-сборка для `SLM Design`.
+- Корневой `llms.txt` как карта всех документаций.
+- Собственные `llms.txt` и `llms-full.txt` внутри каждой документации.
+- Docker/Caddy-конфигурация для публикации статической сборки.
+- Gitea CI/CD для ветки `master`.

-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## Документации

-## Expanding the ESLint configuration
+- `SLM Design` — архитектура frontend-приложений через слои, модули, публичные API и DI через фабрики.
+- `NextJS Style Guide` — будущие правила организации Next.js-приложений.
+- `React Style Guide` — будущие правила написания React-кода.
+- `Figma Adaptive Standards` — будущие стандарты подготовки адаптивных макетов в Figma.

-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+## Структура

-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```text
+canons/                 исходные материалы и черновики
+docs/slm-design/        VitePress-сайт SLM Design
+scripts/docs/           подготовка контента для документаций
+scripts/site/           генерация корневых артефактов сайта
+src/                    React-лендинг
+public/                 статические файлы и сгенерированные документации
 ```

-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+## Команды

-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+npm ci
+npm run dev
 ```
+
+```bash
+npm run docs:build:slm-design
+npm run site:generate
+npm run build
+```
+
+Основные скрипты:
+
+- `npm run dev` — запускает Vite dev server.
+- `npm run docs:build:slm-design` — подготавливает и собирает VitePress-документацию SLM Design.
+- `npm run site:generate` — генерирует корневой `public/llms.txt` из `src/config/docs.config.ts` и хардкод-секций.
+- `npm run build` — генерирует корневые артефакты и собирает лендинг.
+- `npm run lint` — запускает ESLint.
+
+## LLM-артефакты
+
+Корневой файл:
+
+```text
+/llms.txt
+```
+
+Он является навигационной картой пространства документаций и указывает на `llms.txt` конкретных материалов.
+
+Пример проектных артефактов:
+
+```text
+/slm-design/llms.txt
+/slm-design/llms-full.txt
+```
+
+Корневой `llms-full.txt` намеренно не создаётся. Полные bundles остаются внутри конкретных документаций.
+
+## Caddy
+
+`Caddyfile` отдаёт статическую сборку из `/srv`, поддерживает clean URLs и выставляет контекстные `Link` headers:
+
+- `/slm-design/*` → `/slm-design/llms.txt`
+- `/nextjs-style-guide/*` → `/nextjs-style-guide/llms.txt`
+- `/react-style-guide/*` → `/react-style-guide/llms.txt`
+- `/figma-adaptive-standards/*` → `/figma-adaptive-standards/llms.txt`
+- остальные пути → `/llms.txt`
+
+Редиректов `llms.txt` в корень нет.
+
+## Docker
+
+Локальная проверка образа:
+
+```bash
+docker build -t all-docs:test .
+```
+
+Docker-сборка выполняет:
+
+```bash
+npm run docs:build:slm-design
+npm run build
+```
+
+## CI/CD
+
+Workflow находится в `.gitea/workflows/ci.yml`.
+
+Особенности:
+
+- запускается только для ветки `master`;
+- не создаёт версии и теги;
+- собирает документацию, лендинг и Docker-образ;
+- деплоит контейнер `docs` в Docker network `web`.