Платформа этой документации¶

О том, как построен и работает сам этот сайт. Добавление страницы, перевод и развёртывание — всё здесь.

Технологии¶

Компонент	Выбор
Движок	MkDocs
Тема	Material for MkDocs
Многоязычность	`mkdocs-static-i18n`
Диаграммы	Mermaid (встроен в Material)
Результат	Статический HTML — runtime отсутствует

Тот же стек, что и у документации в остальных репозиториях экосистемы, — поэтому перенести страницу или скопировать конфигурацию из одного репозитория в другой просто.

Структура репозитория¶

docs-gerege-mn/
├── mkdocs.yml              # Конфигурация сайта, nav, i18n
├── requirements.txt        # mkdocs-material, mkdocs-static-i18n
├── docs/                   # ← Публикуемое содержимое
│   ├── index.md
│   ├── assets/logo.webp
│   ├── stylesheets/brand.css
│   ├── ecosystem/
│   ├── platforms/
│   ├── standards/
│   └── operations/
├── deploy/                 # Инструменты развёртывания (в сайт НЕ входят)
│   ├── README.md           # Runbook по хосту
│   ├── deploy.sh
│   ├── docker-compose.yml
│   ├── nginx-site.conf
│   └── edge/
│       └── docs.gerege.mn.conf
└── .github/workflows/
    ├── ci.yml
    └── deploy.yml

Всё, что попало в docs/, станет публичным

Сайт открыт в интернете. Адреса серверов, учётные данные, внутренние реестры рисков никогда не должны находиться внутри docs/. Такому материалу место в deploy/ (внутри закрытого репозитория, вне состава сайта).

Локальный запуск¶

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# Сервер разработки — изменения видны сразу
.venv/bin/mkdocs serve

# Production-сборка (strict — предупреждения становятся ошибками)
.venv/bin/mkdocs build --clean --strict

mkdocs serve поднимается на http://127.0.0.1:8000.

Добавление страницы¶

Создайте файл — .md в подходящем каталоге (например, docs/platforms/new.md).
Зарегистрируйте в nav — добавьте в список nav в mkdocs.yml.
Переводы навигации — если добавили новое название пункта меню, внесите его в nav_translations во все шесть локалей (en · ar · zh · fr · ru · es).
Проверьте строгой сборкой — mkdocs build --strict.

Зачем нужен строгий режим

--strict превращает предупреждения в ошибки: битые внутренние ссылки, указанные в nav несуществующие файлы, существующие файлы, не попавшие в nav. CI работает в том же режиме, поэтому локальная проверка спасает PR от падения.

Добавление перевода¶

Сайт выходит на монгольском плюс шесть официальных языков ООН. Используется суффиксная схема — page.md (монгольский) и рядом версии с кодом языка:

docs/platforms/sso.md      ← Монгол (источник)
docs/platforms/sso.ar.md   ← العربية
docs/platforms/sso.zh.md   ← 中文
docs/platforms/sso.en.md   ← English
docs/platforms/sso.fr.md   ← Français
docs/platforms/sso.ru.md   ← Русский
docs/platforms/sso.es.md   ← Español

При добавлении страницы:

Напишите монгольский оригинал и стабилизируйте его строгой сборкой.
Добавьте шесть переводов разом — при частичном переводе содержимое начинает расходиться.
Внесите название пункта меню в nav_translations в mkdocs.yml для всех шести локалей.

Благодаря fallback_to_default: true сайт остаётся целым даже при неполном переводе: страница покажет монгольский оригинал, а не 404.

Подробности — на странице Многоязычность.

Оформление и бренд¶

Цвета собраны в один блок внутри docs/stylesheets/brand.css:

:root {
  --grg-blue:       #004eb6;  /* шапка / глубокий кобальт */
  --grg-blue-2:     #0064e1;  /* бренд */
  --grg-blue-deep:  #003a8a;
  --grg-blue-light: #3990ff;  /* ссылки в тёмной теме */
  --grg-gold:       #e4b24a;  /* ТОЛЬКО для акцента / знаков доверия */
}

Не добавляйте новые hex-значения вне этого блока. Золотой не является брендовым цветом — он только для акцентов и знаков доверия.

Бейджи статуса¶

<span class="grg-badge grg-badge--live">Production</span>
<span class="grg-badge grg-badge--wip">Частично</span>
<span class="grg-badge grg-badge--plan">В планах</span>

Архитектура развёртывания¶

Интернет → edge nginx (gerege-nginx)
              │  vhost docs.gerege.mn
              ▼
       docs-gerege-web  (контейнер nginx:alpine)
              │  общая сеть Docker `gerege`
              ▼
       <путь деплоя>/site  (собранный статический HTML)

Сайт обновляется на месте с помощью rsync: если заменить каталог целиком, контейнер продолжит смотреть на старый inode, и новое содержимое просто не появится.

Почему отдельный контейнер? Добавление нового mount в контейнер edge nginx требует его пересоздания, а при этом ненадолго падают все домены. Отдавая статический сайт из собственного маленького контейнера, на edge достаточно дополнить конфигурацию и выполнить reload.

Владение конфигурацией¶

Этот сайт сам владеет своим edge vhost — deploy/edge/docs.gerege.mn.conf. При каждом деплое этот файл устанавливается в conf.d у edge nginx, проверяется через nginx -t и применяется reload'ом. Developer Portal и Template Platform перешли на ту же модель; sso · dan · gsign · xyp пока обслуживаются из центрального файла.

В результате любое изменение docs.gerege.mn завершается внутри этого репозитория — без PR в чужой репозиторий и без ожидания чужого деплоя.

Чтобы быть полностью независимым, у vhost есть собственная зона rate-limit и собственный блок на порту 80 (ACME + redirect) — он не зависит ни от зоны, ни от default server, объявленных в другом файле.

Общий принцип

Конфигурация, относящаяся только к одному сервису, должна лежать в репозитории этого сервиса. В центральном файле каждое изменение приходится согласовывать с чужим деплоем, а владение размывается.

О том, как перешли к этой модели и почему приняли те или иные решения, — на странице Журнал работ.

Деплой¶

Деплой выполняется автоматически через CI — при push в main:

сборка MkDocs --strict,
копирование архива site/ на сервер,
обновление на месте через rsync,
обновление контейнера,
установка edge vhost → nginx -t → reload,
проверка живого сайта.

Если nginx -t не проходит, возвращается прежняя конфигурация и reload не выполняется — работающий nginx продолжает со своей последней рабочей конфигурацией.

Если нужен ручной деплой, есть скрипт deploy/deploy.sh; подробности по хосту — в закрытом runbook deploy/README.md.

Как внести вклад¶

Создайте ветку (docs/<тема> или feat/<тема>).
Внесите изменение и запустите локально mkdocs build --strict.
Откройте PR — CI выполнит строгую сборку.
После слияния публикация произойдёт автоматически.

Стиль изложения¶

Исходный текст пишите по-монгольски.
Заголовок должен прямо говорить, о чём страница: конкретное лучше, чем «Обзор» или «Введение».
Записывайте причину решения, а не только то, что сделали. «Почему» — информация, которая устаревает медленнее всего.
Риски и предостережения — в блок !!! warning.
Таблица лучше длинного списка.