Aller au contenu

Ressources et médias (images, vidéos, MinIO)

Les images, vidéos et autres binaires de la documentation peuvent être externalisés dans un bucket MinIO (S3-compatible) déjà déployé, pour alléger le dépôt et permettre des fichiers volumineux.

Principe

  • En markdown, vous référencez les ressources par un chemin relatif : assets/images/..., assets/videos/....
  • Si une URL de base (MinIO) est configurée au build, le site généré pointe automatiquement vers le bucket au lieu du site statique.
  • Sans URL de base, les ressources peuvent rester locales (dossier docs/.../assets/ dans le dépôt).

Structure recommandée dans MinIO

Organisation suggérée dans le bucket (ex. admin-docs ou sysgardes-docs) :

bucket/
└── assets/
    ├── images/          # Captures d'écran, schémas, icônes
    │   ├── fr/          # (optionnel) par langue
    │   └── en/
    ├── videos/          # Tutoriels vidéo, démonstrations
    └── pdf/             # Fichiers PDF joints
  • Chemin unique : assets/images/capture-planning.png (partagé fr/en) ou par langue : assets/images/fr/planning.png, assets/images/en/planning.png.

Référencer une ressource dans le markdown

Avec URL de base configurée (MinIO)

Utilisez le chemin relatif assets/... :

![Description de l'image](assets/images/capture-planning.png)

Lors du build, le plugin remplace automatiquement par l’URL complète du bucket (ex. https://minio.example.com/bucket/admin-docs/assets/images/capture-planning.png).

Vidéos

[Voir la démo](assets/videos/demo-planning.mp4)

Ou en HTML si besoin (lecteur vidéo) :

<video controls src="assets/videos/demo-planning.mp4" width="640"></video>

Sans MinIO (ressources locales)

Placez les fichiers dans le dépôt, par exemple :

  • docs/fr/guide/assets/images/ et docs/en/guide/assets/images/

Puis référencez par rapport au dossier assets/ au même niveau que la page, ou utilisez un chemin relatif au fichier .md. Sans assets_base_url, les liens assets/... restent relatifs au site (il faut alors que les fichiers soient copiés dans le build ; voir ci‑dessous).

Configuration de l’URL de base (MinIO)

Dans mkdocs.yml

extra:
  assets_base_url: 'https://minio.votredomaine.bf/bucket/admin-docs'

(Remplacez par l’URL réelle du bucket, sans slash final.)

Au build (CI / Docker)

  • Variable d’environnement : le plugin lit ASSETS_BASE_URL. Exemple :
export ASSETS_BASE_URL=https://minio.example.com/bucket/admin-docs
mkdocs build
  • Docker : transmettre l’argument au build :
docker build --build-arg ASSETS_BASE_URL=https://minio.example.com/bucket/admin-docs -f guide-docs/Dockerfile -t admin-docs .

Upload des fichiers vers MinIO

Client MinIO (mc)

  1. Configurer l’alias (une fois) :
mc alias set myminio https://minio.example.com ACCESS_KEY SECRET_KEY
  1. Créer le bucket si besoin, puis envoyer les fichiers :
mc mb myminio/admin-docs --ignore-existing
mc cp --recursive guide-docs/local-assets/ myminio/admin-docs/assets/

Politique d’accès

  • Pour un site docs public : policy en lecture publique sur le préfixe assets/ (GetObject).
  • Pour un accès restreint : laisser le bucket privé et servir les médias via un reverse‑proxy ou une URL signée (à configurer côté infra).

Récapitulatif

Élément Détail
Où stocker Bucket MinIO (ex. admin-docs), préfixe assets/.
En markdown ![alt](assets/images/nom.png) ou ](assets/videos/nom.mp4).
Build extra.assets_base_url dans mkdocs.yml ou ASSETS_BASE_URL à l’exécution.
Upload mc cp, interface MinIO ou script CI.

Voir aussi : Déploiement et authentification (Keycloak) pour la mise en ligne du site.