# Gitea Pages — Хостинг документации

## 📋 Обзор

**Gitea Pages** — аналог GitHub Pages для хостинга статических сайтов напрямую из Gitea.

**URL документации:** `https://git.much-data.ru/claw/kwork-api/`

---

## 🔧 НАСТРОЙКА

### **Шаг 1: Включить Pages в репозитории**

1. Зайди в https://git.much-data.ru/claw/kwork-api
2. **Settings** → **Pages**
3. Включить **Enable Pages**
4. Выбрать источник:
   - **Source:** `gh-pages` branch
   - **Folder:** `/ (root)`
5. **Save**

---

### **Шаг 2: Настроить Gitea Token**

1. https://git.much-data.ru → Settings → Applications
2. Создать токен с правами:
   - `write:repository`
   - `write:package`
3. Скопировать токен
4. В репозитории: **Settings** → **Secrets**
5. Добавить секрет: `GITEA_TOKEN` = твой токен

---

### **Шаг 3: Первый деплой**

```bash
cd /root/kwork-api

# Собрать документацию
uv run mkdocs build

# Проверить что site/ создан
ls -la site/

# Закоммитить и запушить
git add .
git commit -m "docs: initial documentation"
git push origin main

# CI/CD автоматически задеплоит на gh-pages
```

---

### **Шаг 4: Проверить**

После успешного CI/CD:

**Документация доступна:**
```
https://git.much-data.ru/claw/kwork-api/
```

Или если включён custom domain:
```
https://kwork-api.much-data.ru/
```

---

## 🔄 АВТОМАТИЧЕСКИЙ ДЕПЛОЙ

**Workflow срабатывает при:**
- ✅ Push в `main` ветку
- ✅ Создании тега релиза

**Что делает:**
1. Собирает MkDocs документацию
2. Пушит в `gh-pages` ветку
3. Gitea Pages автоматически обновляет сайт

---

## 🌐 CUSTOM DOMAIN (опционально)

### **DNS настройка:**

```
# В панели управления доменом much-data.ru

# CNAME запись:
kwork-api    CNAME    git.much-data.ru

# Или A запись:
kwork-api    A        5.188.26.192
```

### **В Gitea Pages:**

1. **Settings** → **Pages**
2. **Custom Domain:** `kwork-api.much-data.ru`
3. **Save**

### **Создать CNAME файл:**

```bash
# В корне проекта (не в site/)
echo "kwork-api.much-data.ru" > static/CNAME
git add static/CNAME
git commit -m "docs: add custom domain"
git push
```

---

## 📊 СТРУКТУРА ВЕТКИ

```
main (исходный код)
├── src/
├── docs/
├── mkdocs.yml
└── .github/workflows/ci.yml

gh-pages (автоматически, только сайт)
├── index.html
├── api-reference/
├── search/
└── ...
```

---

## 🔍 TROUBLESHOOTING

### **Pages не включаются:**

```bash
# Проверить что Gitea версия >= 1.19
# Админ должен включить Pages в настройках сервера
```

### **CI/CD ошибка деплоя:**

```bash
# Проверить токен
# Проверить права токена (write:repository)
# Проверить что gh-pages ветка существует
```

### **404 на странице:**

```bash
# Подождать 1-2 минуты (Gitea обрабатывает)
# Проверить что site/ не пустой
# Проверить workflow логи
```

---

## 📋 ЧЕКЛИСТ

- [ ] Включить Pages в настройках репозитория
- [ ] Создать Gitea Token
- [ ] Добавить токен в Secrets (`GITEA_TOKEN`)
- [ ] Запушить изменения в main
- [ ] Дождаться CI/CD
- [ ] Проверить https://git.much-data.ru/claw/kwork-api/
- [ ] (Опционально) Настроить custom domain

---

## 🎯 АЛЬТЕРНАТИВЫ

Если Gitea Pages не работает:

### **1. Netlify (бесплатно)**
```bash
# Подключить репозиторий
# Build command: uv run mkdocs build
# Publish directory: site/
```

### **2. Vercel (бесплатно)**
```bash
# Аналогично Netlify
# Автоматический деплой из Git
```

### **3. Cloudflare Pages (бесплатно)**
```bash
# Быстрый CDN
# Автоматический HTTPS
```

### **4. Своё сервер (nginx)**
```bash
# Скопировать site/ на сервер
# Настроить nginx на /var/www/kwork-api-docs/
```

---

## 📞 ССЫЛКИ

- [Gitea Pages Documentation](https://docs.gitea.com/usage/pages)
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Gitea Actions](https://docs.gitea.com/usage/actions)