Rédaction des pages et médias

Ce guide s'adresse à qui écrit ou relit une page de ce livre. Il décrit comment insérer une image vectorielle, une animation SVG ou une vidéo, avec les classes CSS que le livre fournit. Lisez d'abord le guide de contribution.

Le livre est produit par mdBook. mdBook laisse passer le HTML brut du Markdown sans l'échapper : les balises <figure>, <svg>, <video> et <iframe> ne demandent aucun plugin.

Où vivent les fichiers

book.toml charge media.css et charte.css (clé additional-css) et theme-icon.js, fr.js et recherche-fr.js (clé additional-js). mdBook copie dans le livre tous les fichiers non Markdown du dossier docs/.

Les chemins s'écrivent relativement à la page. Depuis une page de docs/guides/, une image de docs/static/img/ s'écrit ../static/img/<fichier>. Depuis docs/quickstart.md, elle s'écrit ./static/img/<fichier>.

Le livre n'impose pas d'image d'en-tête : aucune page n'en porte aujourd'hui (aucun fichier page-* dans static/img/).

Pour reconstruire et relire le livre :

cargo run -p forge-docs

Résultat attendu : la commande se termine sans erreur mdBook, et le livre construit se lit ensuite sous /docs/ du serveur de développement du frontend (dx serve, port 8080).

Images SVG statiques

Exportez le schéma depuis votre outil vectoriel et retirez les métadonnées inutiles (par exemple avec SVGO). Insérez-le dans un <figure> de classe media-svg : media.css borne la largeur à 720 px, centre la figure et style la légende.

<figure class="media-svg">
  <img
    src="../../static/img/<nom-du-schema>.svg"
    alt="<description du contenu du schéma pour un lecteur d'écran>"
    loading="lazy"
  />
  <figcaption>Légende courte.</figcaption>
</figure>

L'attribut alt est obligatoire et décrit le contenu : « schéma » ou « image » ne décrivent rien. loading="lazy" diffère le chargement jusqu'à ce que l'image approche du cadre visible.

Animations SVG inline

Une animation SVG s'écrit dans le Markdown, entre deux lignes vides, à l'intérieur d'un <figure class="media-svg">. Deux techniques existent :

• CSS (@keyframes) : portable, et la seule que media.css neutralise. Quand le lecteur demande moins de mouvement (prefers-reduced-motion: reduce), la feuille met en pause les animations et les transitions des SVG de la classe media-svg.
• SMIL (<animate>, <animateTransform>) : autonome, mais media.css ne l'arrête pas. Si vous l'utilisez, ajoutez votre propre règle @media (prefers-reduced-motion: reduce) dans le SVG.

Une animation longue ou coûteuse se range dans un fichier .svg séparé de static/img/, inséré comme image statique.

Vidéos

Le livre vise à ne charger aucune ressource tierce : c'est un objectif en cours. Une vidéo hébergée chez un tiers l'enfreint. Choisissez dans cet ordre.

1. Vidéo courte hébergée avec le livre

Pour une vidéo de moins de 30 secondes, déposez un fichier WebM (VP9) dans static/img/ ou un sous-dossier, et lisez-le avec la balise <video>. Aucun tiers n'est contacté. Le prix : la taille du dépôt augmente. N'y mettez pas de vidéo longue.

<div class="media-video">
  <video controls preload="metadata" poster="../static/img/<affiche>.png">
    <source src="../../static/img/<video>.webm" type="video/webm" />
    <track kind="captions" src="../../static/img/<video>.fr.vtt"
           srclang="fr" label="Français" default />
    Votre navigateur ne sait pas lire les vidéos HTML5 :
    <a href="../../static/img/<video>.webm">téléchargez la vidéo</a>.
  </video>
</div>

Aucune vidéo n'est aujourd'hui stockée dans le dépôt (mesure du 2026-10-03 : git ls-files crates/forge-docs/docs | grep -Ei '\.(webm|mp4)$' ne rend rien).

2. Instance PeerTube européenne

PeerTube, plateforme fédérée, expose un lecteur à l'adresse https://<instance>/videos/embed/<identifiant>. Choisissez une instance dont vous maîtrisez l'hébergement et la juridiction.

3. Plateformes hors UE

YouTube et Vimeo sont des services hors UE. Réservez-les aux cas où aucune alternative n'existe, et dites-le dans la revue. Pour YouTube, utilisez le domaine youtube-nocookie.com, qui limite le dépôt de cookies avant la lecture ; cela réduit le suivi, ce n'est pas une garantie juridique, à valider avec votre délégué à la protection des données.

<div class="media-video">
  <iframe
    src="https://www.youtube-nocookie.com/embed/<identifiant-video>"
    title="<titre descriptif de la vidéo>"
    loading="lazy"
    allowfullscreen
    referrerpolicy="strict-origin-when-cross-origin"
  ></iframe>
</div>

media.css donne au conteneur media-video un ratio 16:9 et une largeur maximale de 860 px. L'attribut title est obligatoire : il donne un nom à l'iframe pour les lecteurs d'écran. N'ajoutez jamais autoplay=1 : la feuille entoure d'un liseré orange les vidéos qui démarrent seules pour que la revue l'attrape.

Liste de contrôle avant revue

• Chaque image a un alt non vide et descriptif.
• Chaque <iframe> a un title.
• Les chemins sont relatifs à la page et le livre se construit sans erreur (cargo run -p forge-docs).
• Une animation respecte prefers-reduced-motion.
• Une vidéo avec parole a des sous-titres WebVTT en français. Le référentiel d'accessibilité des services numériques est la norme européenne EN 301 549.
• Aucune vidéo n'utilise autoplay.
• Aucun secret, aucune adresse IP, aucun nom d'hôte interne n'apparaît dans une image, une légende ou un sous-titre : le livre est public.

Aucun script de lint Markdown n'est livré avec le dépôt pour le moment : la vérification est la revue humaine.

Voir aussi

• Contribuer — cadre, hooks et règles de sécurité appliqués à toute contribution
• Fichiers de configuration — le fichier de réglages lu par mdBook pour ce livre
• Conformité RGPD — absence de script ou cookie tiers, mesure d'audience auto-hébergée
• Gaia-X — résidence des contenus et refus des ressources hors UE
• Sécurité — pourquoi aucun secret ni nom d'hôte interne ne doit paraître