docs: добавить описание проекта
- добавлено назначение хаба документаций - описаны структура проекта и основные команды - задокументированы LLM-артефакты, Caddy, Docker и CI/CD
This commit is contained in:
159
README.md
159
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
|
```text
|
||||||
export default defineConfig([
|
canons/ исходные материалы и черновики
|
||||||
globalIgnores(['dist']),
|
docs/slm-design/ VitePress-сайт SLM Design
|
||||||
{
|
scripts/docs/ подготовка контента для документаций
|
||||||
files: ['**/*.{ts,tsx}'],
|
scripts/site/ генерация корневых артефактов сайта
|
||||||
extends: [
|
src/ React-лендинг
|
||||||
// Other configs...
|
public/ статические файлы и сгенерированные документации
|
||||||
|
|
||||||
// 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...
|
|
||||||
},
|
|
||||||
},
|
|
||||||
])
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
```bash
|
||||||
// eslint.config.js
|
npm ci
|
||||||
import reactX from 'eslint-plugin-react-x'
|
npm run dev
|
||||||
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 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`.
|
||||||
|
|||||||
Reference in New Issue
Block a user