Энэ баримтын платформ¶

Энэ сайт өөрөө хэрхэн бүтээгдэж, ажиллаж байгаа тухай. Хуудас нэмэх, орчуулах, байршуулах бүх зүйл энд.

Технологи¶

Бүрэлдэхүүн	Сонголт
Хөдөлгүүр	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/ дотор орсон бүхэн нийтэд ил гарна

Сайт нь интернэтэд нээлттэй. Серверийн хаяг, credential, дотоод эрсдэлийн бүртгэл зэрэг нь docs/ дотор хэзээ ч байрлахгүй. Ийм зүйл deploy/ хавтаст (хаалттай репо дотор, сайтад ороогүй) байрлана.

Локал ажиллуулах¶

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

# Хөгжүүлэлтийн сервер — өөрчлөлт шууд харагдана
.venv/bin/mkdocs serve

# Production build (strict — анхааруулга нь алдаа)
.venv/bin/mkdocs build --clean --strict

mkdocs serve нь http://127.0.0.1:8000 дээр асна.

Хуудас нэмэх¶

Файл үүсгэ — зохих хавтаст .md файл (жишээ нь docs/platforms/new.md).
nav-д бүртгэ — mkdocs.yml доторх nav жагсаалтад нэм.
Nav орчуулга — шинэ цэсний нэр нэмсэн бол nav_translations-д зургаан локал бүрд нэм (en · ar · zh · fr · ru · es).
Strict build-ээр шалга — mkdocs build --strict.

Strict горим яагаад хэрэгтэй вэ?

--strict нь анхааруулгыг алдаа болгоно: эвдэрсэн дотоод холбоос, nav-д заасан ч байхгүй файл, байгаа ч nav-д ороогүй файл. CI мөн адил горимоор ажилладаг тул локал дээр шалгах нь PR унахаас сэргийлнэ.

Орчуулга нэмэх¶

Сайт нь Монгол дээр нэмээд НҮБ-ын зургаан албан ёсны хэлээр үйлчилнэ. Suffix бүтэц ашиглана — 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

Шинэ хуудас нэмэхэд:

Монгол эхийг бич, strict build-ээр тогтворжуул.
Зургаан орчуулгыг нэг дор нэм — хэсэгчилбэл агуулга зөрнө.
mkdocs.yml-ийн nav_translations-д цэсний нэрийг зургаан локал бүрд нэм.

fallback_to_default: true тул орчуулга дутуу байсан ч сайт бүтэн ажиллана — тэр хуудас Монгол эхээ харуулна, 404 гарахгүй.

Дэлгэрэнгүйг Олон хэл (i18n) хуудаснаас.

Загвар ба брэнд¶

Өнгө нь 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)
              │  docs.gerege.mn vhost
              ▼
       docs-gerege-web  (nginx:alpine контейнер)
              │  дундын `gerege` Docker сүлжээ
              ▼
       <deploy зам>/site  (build хийсэн статик HTML)

Сайт нь rsync-ээр байрандаа шинэчлэгддэг — хавтсыг бүтнээр нь солиход контейнер хуучин inode-оо харсаар үлддэг тул шинэ агуулга гарч ирэхгүй.

Яагаад тусдаа контейнер вэ? Edge nginx-ийн контейнерт шинэ mount нэмэх нь түүнийг дахин үүсгэхийг шаардана — тэр үед бүх домэйн түр унана. Статик сайтыг өөрийн жижиг контейнерээр үйлчилснээр edge-д зөвхөн конфигийн нэмэлт хийж, reload-оор өнгөрнө.

Конфигийн өмчлөл¶

Энэ сайт өөрийн edge vhost-оо өөрөө эзэмшинэ — deploy/edge/docs.gerege.mn.conf. Deploy бүрд тэр файл edge nginx-ийн conf.d руу суулгагдаж, nginx -t шалгагдаад reload хийгддэг. Developer Portal ба Template Platform мөн ижил загварт шилжсэн; sso · dan · gsign · xyp одоогоор төвлөрсөн файлаар үйлчлэгдэж байна.

Ингэснээр docs.gerege.mn-ийн ямар ч өөрчлөлт энэ репо дотор дуусна — өөр репо-д PR илгээх, өөр багийн deploy хүлээх шаардлагагүй.

Бүрэн хараат бус байхын тулд vhost нь өөрийн rate-limit zone болон өөрийн port-80 блоктой (ACME + redirect) — өөр файлд тодорхойлогдсон zone эсвэл default server рүү хамааралгүй.

Ерөнхий зарчим

Тодорхой нэг үйлчилгээнд л хамаарах конфиг нь тэр үйлчилгээний репо-д байх нь зөв. Төвлөрсөн файлд хийвэл өөрчлөлт бүр өөр багийн deploy-той уялдах шаардлагатай болж, өмчлөл бүрхэг болно.

Энэ загварт хэрхэн шилжсэн, ямар шийдвэр яагаад гарсныг Хийгдсэн ажил хуудаснаас үзнэ үү.

Deploy¶

Deploy нь CI-гаар автоматаар явагдана — main руу push хийхэд:

MkDocs --strict build,
site/ архивыг сервер лүү хуулах,
rsync-ээр байрандаа шинэчлэх,
контейнерийг шинэчлэх,
edge vhost суулгах → nginx -t → reload,
амьд сайтыг шалгах.

nginx -t унавал өмнөх конфиг буцаагдаж, reload хийгдэхгүй — ажиллаж буй nginx хуучин сайн конфигоороо үргэлжилнэ.

Гараар deploy хийх шаардлагатай бол deploy/deploy.sh скрипт бий — хостын дэлгэрэнгүйг deploy/README.md хаалттай runbook-оос үзнэ үү.

Хувь нэмэр оруулах¶

Branch үүсгэ (docs/<сэдэв> эсвэл feat/<сэдэв>).
Өөрчлөлтөө хийж, локал дээр mkdocs build --strict ажиллуул.
PR нээ — CI нь strict build ажиллуулна.
Нэгтгэсний дараа автоматаар нийтлэгдэнэ.

Бичих хэв маяг¶

Монголоор эх бичвэрийг бич.
Гарчиг нь юуны тухай болохыг шууд хэл — «Тойм», «Танилцуулга» гэхээс тодорхой нь дээр.
Шийдвэрийн шалтгааныг бич, зөвхөн юу хийснийг биш. «Яагаад» гэдэг нь хамгийн хурдан хуучирдаггүй мэдээлэл.
Эрсдэл, анхаарах зүйлийг !!! warning блокт.
Хүснэгт нь урт жагсаалтаас дээр.