Добавить сервис FAQ (mkdocs + nginx) для faq.khap.ru

Статический сайт документации Королевский Хап, ранее хостившийся на GitHub Pages (faq.wb10.ru). Контент перенесён из faq-master.zip. - MkDocs (Material theme) собирает статику в Dockerfile (python:3.11-slim) - nginx:alpine отдаёт сайт на порту 80 (хост 8094) - CI: сборка образа + SSH-деплой на khap.ru
2026-08-09 22:22:57 +03:00
parent 1f6ad4439c
commit 2ee71e633e
38 changed files with 680 additions and 2 deletions
@@ -0,0 +1,52 @@
+# 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 пути, при переносе файлов не переименовывать.