S.Gromov
a9e18f9269
- добавлено назначение хаба документаций - описаны структура проекта и основные команды - задокументированы LLM-артефакты, Caddy, Docker и CI/CD
111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# Документация
|
||
|
||
Единое пространство для идей, черновиков и первых версий документаций, которые ещё формируются и постепенно становятся самостоятельными материалами.
|
||
|
||
Проект собирает рабочие документации, стандарты и LLM-артефакты в одном месте, чтобы не создавать отдельное пространство для каждого материала на ранней стадии.
|
||
|
||
## Что внутри
|
||
|
||
- React/Vite-лендинг со списком документаций.
|
||
- VitePress-сборка для `SLM Design`.
|
||
- Корневой `llms.txt` как карта всех документаций.
|
||
- Собственные `llms.txt` и `llms-full.txt` внутри каждой документации.
|
||
- Docker/Caddy-конфигурация для публикации статической сборки.
|
||
- Gitea CI/CD для ветки `master`.
|
||
|
||
## Документации
|
||
|
||
- `SLM Design` — архитектура frontend-приложений через слои, модули, публичные API и DI через фабрики.
|
||
- `NextJS Style Guide` — будущие правила организации Next.js-приложений.
|
||
- `React Style Guide` — будущие правила написания React-кода.
|
||
- `Figma Adaptive Standards` — будущие стандарты подготовки адаптивных макетов в Figma.
|
||
|
||
## Структура
|
||
|
||
```text
|
||
canons/ исходные материалы и черновики
|
||
docs/slm-design/ VitePress-сайт SLM Design
|
||
scripts/docs/ подготовка контента для документаций
|
||
scripts/site/ генерация корневых артефактов сайта
|
||
src/ React-лендинг
|
||
public/ статические файлы и сгенерированные документации
|
||
```
|
||
|
||
## Команды
|
||
|
||
```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`.
|