# faq-khap-ru

FAQ Королевский Хап — сайт документации по боту «Королевский Хап», отдаётся как статический сайт по адресу https://faq.khap.ru.

## Стек

- **MkDocs + Material theme** — исходники документации в `docs/` (markdown + картинки), конфиг `mkdocs.yml`.
- **Docker multi-stage** (`Dockerfile`): стадия `build` на `python:3.11-slim` собирает статику (`mkdocs build`), финальный образ — `nginx:alpine`, отдаёт собранный сайт из `/usr/share/nginx/html`.
- **docker-compose** — прод-запуск: сервис `faq`, образ `gitea.yandex5.ru/monster/faq-khap-ru:master`, порт хоста `8094` → контейнера `80`.

## Точки входа

- Локально: `python3 -m venv .venv && .venv/bin/pip install mkdocs-material mkdocs_pymdownx_material_extras && .venv/bin/mkdocs serve`.
- Проверка сборки: `.venv/bin/mkdocs build --site-dir /tmp/faq-site`.
- Прод: Docker-образ по `Dockerfile`, поднимается сервисом `faq` в `docker-compose.yaml` (порт `8094:80`).
- CI/CD: `.github/workflows/docker-image.yml` — на push в `master` собирает и пушит образ в `gitea.yandex5.ru/monster/faq-khap-ru`, затем по SSH деплоит на khap.ru (порт 221, папка `docker.services/faq-khap-ru`).

## Конфигурация

- `mkdocs.yml` — конфиг MkDocs: тема material, навигация (`nav`), markdown-расширения (pymdownx и др.), плагин `search` (ru/en). `site_url: https://faq.khap.ru`.
- Внешняя маршрутизация: `faq.khap.ru` проксируется nginx на khap.ru на контейнер (порт `8094`).
- Переменные окружения не требуются — сайт полностью статический.

## Структура директорий

```
faq-khap-ru/
├── mkdocs.yml                # конфиг MkDocs (тема, nav, расширения)
├── docs/                     # markdown-исходники документации
│   ├── *.md                  # страницы (rules, payment, content, gatekeeper, knopka, autobot_*, app, review, index)
│   └── img/                  # картинки страниц
├── theme/                    # кастомные css/js для темы material
├── Dockerfile                # multi-stage: mkdocs build → nginx
├── docker-compose.yaml       # сервис faq, порт 8094:80
├── .github/workflows/docker-image.yml  # CI: сборка образа + SSH-деплой на khap.ru
├── .gitignore
├── README.md
└── AGENTS.md
```

## Паттерны добавления функциональности

- Новая страница FAQ: добавить `docs/<name>.md` и прописать её в `nav` в `mkdocs.yml`.
- Новые картинки: класть в `docs/img/`, ссылаться относительными путями.
- Изменения в теме: править файлы в `theme/` (подключены через `custom_dir` в `mkdocs.yml`).

## Известные особенности

- **Ранее хостился на GitHub Pages** (`faq.wb10.ru`, репозиторий `korolevskiyhap/faq`, деплой через `mkdocs gh-deploy`). Перенесён в отдельный сервис `monster/faq-khap-ru` на khap.ru, домен `faq.khap.ru`.
- Контент последний раз обновлялся 06.10.2022 (по датам файлов в архиве) — актуальность информации требуется подтверждать у владельца.
- Сайт статический, поиск работает только на клиентской стороне (плагин `search` MkDocs).
- В `docs/` есть картинки с пробелами в именах файлов (`img/visual/pic 3.jpg`) — в ссылках markdown используются URL-encoded пути, при переносе файлов не переименовывать.