Cette plateforme documentaire¶

Comment ce site est lui-même construit et exploité. Ajouter une page, la traduire, la déployer : tout est ici.

Technologie¶

Composant	Choix
Moteur	MkDocs
Thème	Material for MkDocs
Multilingue	`mkdocs-static-i18n`
Diagrammes	Mermaid (intégré à Material)
Résultat	HTML statique — aucun runtime

La même stack que la documentation des autres dépôts de l'écosystème : il est donc facile de déplacer une page ou de copier une configuration d'un dépôt à l'autre.

Structure du dépôt¶

docs-gerege-mn/
├── mkdocs.yml              # Configuration du site, nav, i18n
├── requirements.txt        # mkdocs-material, mkdocs-static-i18n
├── docs/                   # ← Le contenu publié
│   ├── index.md
│   ├── assets/logo.webp
│   ├── stylesheets/brand.css
│   ├── ecosystem/
│   ├── platforms/
│   ├── standards/
│   └── operations/
├── deploy/                 # Outillage de déploiement (NE fait PAS partie du site)
│   ├── README.md           # Le runbook de l'hôte
│   ├── deploy.sh
│   ├── docker-compose.yml
│   ├── nginx-site.conf
│   └── edge/
│       └── docs.gerege.mn.conf
└── .github/workflows/
    ├── ci.yml
    └── deploy.yml

Tout ce qui entre dans docs/ devient public

Le site est ouvert sur Internet. Adresses de serveurs, identifiants, registres de risques internes ne doivent jamais se trouver dans docs/. Ce type de contenu appartient à deploy/ (dans le dépôt privé, hors du site).

Exécution en local¶

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

# Serveur de développement — les changements sont visibles immédiatement
.venv/bin/mkdocs serve

# Build de production (strict — les avertissements deviennent des erreurs)
.venv/bin/mkdocs build --clean --strict

mkdocs serve démarre sur http://127.0.0.1:8000.

Ajouter une page¶

Créez le fichier — un .md dans le répertoire approprié (par exemple docs/platforms/new.md).
Déclarez-le dans nav — ajoutez-le à la liste nav de mkdocs.yml.
Traductions de la navigation — si vous avez ajouté un nouveau libellé de menu, ajoutez-le à nav_translations pour les six locales (en · ar · zh · fr · ru · es).
Vérifiez par un build strict — mkdocs build --strict.

Pourquoi le mode strict est utile

--strict transforme les avertissements en erreurs : liens internes cassés, fichiers déclarés dans nav mais inexistants, fichiers existants absents de nav. La CI tourne dans le même mode, donc vérifier en local évite de faire échouer la PR.

Ajouter une traduction¶

Le site est servi en mongol plus les six langues officielles de l'ONU. Il utilise la structure par suffixe — page.md (mongol) accompagné de versions portant un code de langue :

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

Lors de l'ajout d'une page :

Rédigez l'original mongol et stabilisez-le par un build strict.
Ajoutez les six traductions ensemble : procéder par morceaux laisse le contenu diverger.
Ajoutez le libellé de menu à nav_translations dans mkdocs.yml pour les six locales.

Grâce à fallback_to_default: true, le site reste complet même s'il manque des traductions : la page affiche l'original mongol plutôt qu'un 404.

Voir Internationalisation pour le détail.

Thème et marque¶

Les couleurs sont regroupées dans un seul bloc de docs/stylesheets/brand.css :

:root {
  --grg-blue:       #004eb6;  /* en-tête / cobalt profond */
  --grg-blue-2:     #0064e1;  /* marque */
  --grg-blue-deep:  #003a8a;
  --grg-blue-light: #3990ff;  /* liens en mode sombre */
  --grg-gold:       #e4b24a;  /* UNIQUEMENT accent / marques de confiance */
}

N'ajoutez pas de nouvelles valeurs hexadécimales hors de ce bloc. L'or n'est pas une couleur de marque : il sert seulement à la mise en valeur et aux marques de confiance.

Badges d'état¶

<span class="grg-badge grg-badge--live">Production</span>
<span class="grg-badge grg-badge--wip">Partiel</span>
<span class="grg-badge grg-badge--plan">Prévu</span>

Architecture de déploiement¶

Internet → edge nginx (gerege-nginx)
              │  vhost docs.gerege.mn
              ▼
       docs-gerege-web  (conteneur nginx:alpine)
              │  réseau Docker partagé `gerege`
              ▼
       <chemin de déploiement>/site  (le HTML statique construit)

Le site est mis à jour sur place avec rsync : remplacer le répertoire en bloc laisserait le conteneur pointer sur l'ancien inode, et le nouveau contenu n'apparaîtrait jamais.

Pourquoi un conteneur distinct ? Ajouter un montage au conteneur de l'edge nginx impose de le recréer — et à ce moment-là tous les domaines tombent brièvement. En servant le site statique depuis son propre petit conteneur, l'edge n'a besoin que d'un ajout de configuration et d'un reload.

Propriété de la configuration¶

Ce site possède son propre vhost edge — deploy/edge/docs.gerege.mn.conf. À chaque déploiement, ce fichier est installé dans le conf.d de l'edge nginx, validé par nginx -t puis appliqué par un reload. Le Developer Portal et la Template Platform ont adopté le même modèle ; sso · dan · gsign · xyp sont pour l'instant encore servis depuis le fichier central.

Résultat : toute modification de docs.gerege.mn se termine dans ce dépôt — sans PR vers un autre dépôt ni attente du déploiement d'une autre équipe.

Pour être pleinement autonome, le vhost dispose de sa propre zone de rate-limit et de son propre bloc sur le port 80 (ACME + redirection) : il ne dépend d'aucune zone ni d'aucun default server défini dans un autre fichier.

Le principe général

Une configuration qui ne concerne qu'un seul service a sa place dans le dépôt de ce service. Dans un fichier central, chaque modification doit être coordonnée avec le déploiement d'une autre équipe et la propriété devient floue.

Pour savoir comment ce modèle a été adopté et pourquoi chaque décision a été prise, voir Journal des travaux.

Déploiement¶

Le déploiement se fait automatiquement par la CI — à chaque push sur main :

build MkDocs --strict,
copie de l'archive site/ sur le serveur,
mise à jour sur place par rsync,
rafraîchissement du conteneur,
installation du vhost edge → nginx -t → reload,
vérification du site en ligne.

Si nginx -t échoue, la configuration précédente est restaurée et aucun reload n'a lieu : le nginx en service continue avec sa dernière configuration valide.

En cas de besoin d'un déploiement manuel, un script deploy/deploy.sh existe — pour les détails propres à l'hôte, voir le runbook fermé deploy/README.md.

Contribuer¶

Créez une branche (docs/<sujet> ou feat/<sujet>).
Faites votre modification et lancez mkdocs build --strict en local.
Ouvrez une PR — la CI exécute le build strict.
Après la fusion, la publication est automatique.

Style rédactionnel¶

Rédigez le texte source en mongol.
Que le titre dise directement de quoi parle la page : précis vaut mieux que « Vue d'ensemble » ou « Introduction ».
Notez la raison d'une décision, pas seulement ce qui a été fait. Le « pourquoi » est l'information qui vieillit le plus lentement.
Mettez les risques et les mises en garde dans un bloc !!! warning.
Un tableau vaut mieux qu'une longue liste.