本文档平台¶

本站自身是如何构建与运行的。新增页面、翻译、部署——都在这一页。

技术¶

组件	选型
引擎	MkDocs
主题	Material for MkDocs
多语言	`mkdocs-static-i18n`
图示	Mermaid（Material 内置）
产物	静态 HTML——没有运行时

与生态系统其他仓库的文档采用同一套技术栈——因此在仓库之间搬移页面、复制配置都很容易。

仓库结构¶

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

# 生产构建（strict——警告即错误）
.venv/bin/mkdocs build --clean --strict

mkdocs serve 会在 http://127.0.0.1:8000 启动。

新增页面¶

创建文件——在相应目录下新建 .md（例如 docs/platforms/new.md）。
登记到 nav——加入 mkdocs.yml 的 nav 列表。
导航翻译——若新增了菜单标题，需为全部六个 locale（en · ar · zh · fr · ru · es）在 nav_translations 中补上。
用 strict 构建校验——mkdocs build --strict。

为什么需要 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

新增页面时：

先写好蒙古语原文，并用 strict 构建将其稳定下来。
六种翻译一并补齐——零敲碎打会让内容彼此偏离。
在 mkdocs.yml 的 nav_translations 中为全部六个 locale 补上菜单标题。

由于 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)
              │  docs.gerege.mn vhost
              ▼
       docs-gerege-web  (nginx:alpine 容器)
              │  共享的 `gerege` Docker 网络
              ▼
       <部署路径>/site  (构建好的静态 HTML)

站点通过 rsync 原地更新——如果整个目录替换掉，容器仍会盯着旧的 inode，新内容根本不会出现。

为什么要单独一个容器？ 给 edge nginx 容器新增 mount 就必须重建它，而那一刻所有域名都会短暂中断。把静态站点交给自己的小容器来服务， edge 侧只需追加配置并 reload 即可。

配置的归属¶

本站自己持有自己的 edge vhost——deploy/edge/docs.gerege.mn.conf。每次部署都会把该文件安装到 edge nginx 的 conf.d，经 nginx -t 校验后以 reload 生效。Developer Portal 与 Template Platform 也已转向同一模型； sso · dan · gsign · xyp 目前仍由集中式文件提供。

由此，docs.gerege.mn 的任何变更都在本仓库内部闭环——无需向别的仓库提 PR，也不必等待其他团队部署。

为了彻底独立，该 vhost 拥有自己的限流 zone 和自己的 80 端口块（ACME + 跳转） ——不依赖定义在其他文件中的 zone 或 default server。

一般原则

只与某一个服务相关的配置，理应放在该服务自己的仓库里。若放进集中式文件，每次改动都得与其他团队的部署相互配合，归属也会变得含混。

关于如何转向这一模型、各项决策因何而定，请见工作记录。

部署¶

部署由 CI 自动完成——向 main 推送时：

MkDocs --strict 构建；
把 site/ 归档复制到服务器；
用 rsync 原地更新；
刷新容器；
安装 edge vhost → nginx -t → reload；
校验线上站点。

若 nginx -t 失败，则回退到先前的配置且不执行 reload——正在运行的 nginx 继续沿用它上一份可用配置。

若需手动部署，可使用 deploy/deploy.sh 脚本——主机相关细节见 deploy/README.md 这份封闭 runbook。

如何参与¶

建立分支（docs/<主题> 或 feat/<主题>）。
完成修改，并在本地运行 mkdocs build --strict。
提交 PR——CI 会执行 strict 构建。
合并之后即自动发布。

写作风格¶

原文请用蒙古语书写。
标题要直接说明这一页讲什么——具体的标题胜过「概览」「简介」。
写下决策的原因，而不只是做了什么。「为什么」是最不容易过时的信息。
风险与注意事项放进 !!! warning 块。
表格胜过冗长的列表。