Esta plataforma documental¶

Cómo está construido y cómo funciona este mismo sitio. Añadir una página, traducirla y desplegarla: todo está aquí.

Tecnología¶

Componente	Elección
Motor	MkDocs
Tema	Material for MkDocs
Multilingüe	`mkdocs-static-i18n`
Diagramas	Mermaid (integrado en Material)
Resultado	HTML estático — sin runtime

El mismo stack que la documentación de los demás repositorios del ecosistema, de modo que mover una página o copiar una configuración de un repositorio a otro resulta sencillo.

Estructura del repositorio¶

docs-gerege-mn/
├── mkdocs.yml              # Configuración del sitio, nav, i18n
├── requirements.txt        # mkdocs-material, mkdocs-static-i18n
├── docs/                   # ← El contenido publicado
│   ├── index.md
│   ├── assets/logo.webp
│   ├── stylesheets/brand.css
│   ├── ecosystem/
│   ├── platforms/
│   ├── standards/
│   └── operations/
├── deploy/                 # Herramientas de despliegue (NO forman parte del sitio)
│   ├── README.md           # El runbook del host
│   ├── deploy.sh
│   ├── docker-compose.yml
│   ├── nginx-site.conf
│   └── edge/
│       └── docs.gerege.mn.conf
└── .github/workflows/
    ├── ci.yml
    └── deploy.yml

Todo lo que entra en docs/ se hace público

El sitio está abierto a internet. Direcciones de servidores, credenciales o registros internos de riesgos nunca deben estar dentro de docs/. Ese material pertenece a deploy/ (dentro del repositorio privado y fuera del sitio).

Ejecutarlo en local¶

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

# Servidor de desarrollo — los cambios se ven al instante
.venv/bin/mkdocs serve

# Build de producción (strict — los avisos se vuelven errores)
.venv/bin/mkdocs build --clean --strict

mkdocs serve arranca en http://127.0.0.1:8000.

Añadir una página¶

Cree el fichero — un .md en el directorio adecuado (por ejemplo docs/platforms/new.md).
Regístrelo en nav — añádalo a la lista nav de mkdocs.yml.
Traducciones de la navegación — si ha añadido una etiqueta de menú nueva, inclúyala en nav_translations para los seis locales (en · ar · zh · fr · ru · es).
Compruébelo con un build estricto — mkdocs build --strict.

Por qué hace falta el modo estricto

--strict convierte los avisos en errores: enlaces internos rotos, ficheros declarados en nav que no existen y ficheros que existen pero faltan en nav. La CI funciona en el mismo modo, así que comprobarlo en local evita que el PR falle.

Añadir una traducción¶

El sitio se publica en mongol más los seis idiomas oficiales de la ONU. Usa la estructura por sufijo — page.md (mongol) junto a las versiones con código de idioma:

docs/platforms/sso.md      ← Монгол (origen)
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

Al añadir una página:

Escriba el original en mongol y estabilícelo con un build estricto.
Añada las seis traducciones a la vez: hacerlo por partes deja que el contenido se separe.
Añada la etiqueta de menú a nav_translations en mkdocs.yml para los seis locales.

Gracias a fallback_to_default: true, el sitio sigue completo aunque falten traducciones: la página muestra el original mongol en lugar de un 404.

Véase Internacionalización para el detalle.

Tema y marca¶

Los colores están concentrados en un único bloque dentro de docs/stylesheets/brand.css:

:root {
  --grg-blue:       #004eb6;  /* cabecera / cobalto profundo */
  --grg-blue-2:     #0064e1;  /* marca */
  --grg-blue-deep:  #003a8a;
  --grg-blue-light: #3990ff;  /* enlaces en modo oscuro */
  --grg-gold:       #e4b24a;  /* SOLO para destacar / marcas de confianza */
}

No añada valores hex nuevos fuera de este bloque. El dorado no es un color de marca: sirve solo para destacar y para marcas de confianza.

Etiquetas de estado¶

<span class="grg-badge grg-badge--live">Production</span>
<span class="grg-badge grg-badge--wip">Parcial</span>
<span class="grg-badge grg-badge--plan">Planificado</span>

Arquitectura del despliegue¶

Internet → edge nginx (gerege-nginx)
              │  vhost docs.gerege.mn
              ▼
       docs-gerege-web  (contenedor nginx:alpine)
              │  red Docker compartida `gerege`
              ▼
       <ruta de despliegue>/site  (el HTML estático construido)

El sitio se actualiza in situ con rsync: sustituir el directorio entero dejaría al contenedor mirando al inode antiguo, y el contenido nuevo no aparecería nunca.

¿Por qué un contenedor aparte? Añadir un mount nuevo al contenedor del edge nginx obliga a recrearlo, y en ese momento todos los dominios caen un instante. Al servir el sitio estático desde su propio contenedor pequeño, al edge le basta con una adición de configuración y un reload.

Propiedad de la configuración¶

Este sitio posee su propio vhost del edge: deploy/edge/docs.gerege.mn.conf. En cada despliegue ese fichero se instala en el conf.d del edge nginx, se valida con nginx -t y se aplica con un reload. El Developer Portal y la Template Platform han pasado al mismo modelo; sso · dan · gsign · xyp se sirven de momento desde el fichero central.

El efecto es que cualquier cambio en docs.gerege.mn se completa dentro de este repositorio: sin PR a otro repositorio ni espera al despliegue de otro equipo.

Para ser plenamente independiente, el vhost tiene su propia zona de rate-limit y su propio bloque en el puerto 80 (ACME + redirección): no depende de ninguna zona ni default server definidos en otro fichero.

El principio general

La configuración que solo atañe a un servicio debe estar en el repositorio de ese servicio. Si se pone en un fichero central, cada cambio hay que coordinarlo con el despliegue de otro equipo y la propiedad se difumina.

Sobre cómo se llegó a este modelo y por qué se tomó cada decisión, véase Registro de trabajo.

Despliegue¶

El despliegue ocurre automáticamente por CI — al hacer push a main:

build de MkDocs --strict,
copiar el archivo site/ al servidor,
actualizarlo in situ con rsync,
refrescar el contenedor,
instalar el vhost del edge → nginx -t → reload,
comprobar el sitio en vivo.

Si nginx -t falla, se restaura la configuración anterior y no se hace reload: el nginx en marcha continúa con su última configuración buena.

Si hace falta un despliegue manual existe el script deploy/deploy.sh; para los detalles del host, véase el runbook cerrado deploy/README.md.

Cómo contribuir¶

Cree una rama (docs/<tema> o feat/<tema>).
Haga su cambio y ejecute mkdocs build --strict en local.
Abra un PR — la CI ejecuta el build estricto.
Tras la fusión se publica automáticamente.

Estilo de redacción¶

Escriba el texto de origen en mongol.
Que el título diga directamente de qué trata la página: lo concreto es mejor que «Visión general» o «Introducción».
Anote el motivo de una decisión, no solo lo que se hizo. El «porqué» es la información que envejece más despacio.
Ponga riesgos y advertencias en un bloque !!! warning.
Una tabla es mejor que una lista larga.