Pourquoi CKEditor 5 exige une configuration explicite
CKEditor 5 stocke le contenu en HTML5 pur, sans les balises propriétaires de la version 4. Cette rupture a des conséquences concrètes : des styles appliqués par CKEditor 4 peuvent être silencieusement supprimés lors du premier enregistrement si le filtre HTML de Drupal ne les autorise pas. Une configuration par défaut est rarement suffisante pour une organisation qui a des règles éditoriales précises.
Les trois problèmes les plus fréquents : des styles inline qui persistent après coller depuis Word, des media embeds qui disparaissent à la republication, et des éditeurs qui contournent les contraintes en passant par la vue Source.
Les formats de texte : le point d'entrée de la gouvernance
Trois formats, trois usages distincts
Drupal fournit par défaut trois formats de texte : Basic HTML, Restricted HTML et Full HTML. Ces formats ne sont pas interchangeables : chacun définit les balises autorisées, les filtres appliqués et l'ensemble de plugins CKEditor disponibles pour les éditeurs qui lui sont assignés.
La décision la plus structurante est de définir quel format reçoit quel rôle. Les contributeurs occasionnels n'ont pas besoin de Full HTML. Les éditeurs de contenu éditorial travaillent bien avec un format intermédiaire, bien configuré, qui inclut les titres, les listes, les blocs de citation et les liens.
Configurer via les fichiers YAML de configuration
Chaque format de texte et son éditeur associé sont décrits dans deux fichiers de configuration exportés : filter.format.<machine_name>.yml (les filtres du format) et editor.editor.<machine_name>.yml (la configuration CKEditor : barre d'outils, plugins actifs, styles).
Le déploiement via le système de configuration Drupal (drush config:import) garantit que la configuration est identique sur tous les environnements. C'est le seul moyen de s'assurer que ce qui est validé en staging est exactement ce qui arrive en production.
Les styles autorisés : construire une liste blanche cohérente
Le principe des balises autorisées
Le filtre « Limiter les balises HTML autorisées » dans Drupal est la première ligne de contrôle. Il définit ce que le contenu peut contenir après enregistrement, indépendamment de ce que l'éditeur affiche. Si une balise n'est pas dans cette liste, elle est supprimée lors de l'enregistrement.
Pour un format éditorial standard, la liste des balises utiles inclut : <p>, <h2>, <h3>, <h4>, <strong>, <em>, <a href hreflang>, <ul>, <ol>, <li>, <blockquote>, <code>, <pre>, <br>, ainsi que les attributs data-entity-* pour les images et <drupal-media> pour les embeds.
Ce qu'il faut bloquer explicitement
Les balises à risque sont celles qui transportent du style : <div> sans classe définie, <span style>, <font>, <table> sans contrainte de classe. Elles arrivent principalement par copier-coller depuis Word ou des CMS tiers. Le filtre HTML les supprime si elles ne sont pas listées.
L'attribut style sur toutes les balises doit être absent de la liste autorisée pour les formats non techniques, ou limité à une liste blanche précise de propriétés CSS pour les formats avancés.
Configurer le paste-clean : arrêter le HTML de Word en amont
Le problème du coller depuis Word
Word génère un HTML dense en balises propriétaires, en attributs de style inline et en commentaires XML. Quand un éditeur colle depuis Word dans CKEditor 5, ce contenu arrive brut avant d'être filtré par Drupal. Sans configuration du paste-clean, des mso-* et des font-size inline se retrouvent en base de données, puis remontent dans le rendu HTML.
CKEditor 5 inclut le plugin PasteFromOffice dans le paquet officiel. Ce plugin nettoie automatiquement le HTML issu de Word et de Google Docs lors du collage. Il faut l'activer explicitement dans la configuration de l'éditeur.
Configuration recommandée
Dans editor.editor.<machine_name>.yml, activez pasteFromOffice: true dans les settings de configuration. Combinez cette option avec le plugin RemoveFormat disponible dans la barre d'outils : un bouton qui permet aux éditeurs de supprimer les formats résiduels sur une sélection.
Pour les cas où les éditeurs collent fréquemment depuis des sources web, PastePlainText (coller en texte brut via Maj+Ctrl+V) est une alternative utile à documenter dans le guide éditorial.
Media embeds : configurer sans créer de contenus orphelins
Le pipeline de filtres et son ordre
Drupal applique les filtres de texte dans un ordre précis défini dans le format. Pour les media embeds, cet ordre est déterminant : le filtre media_embed doit être activé, et il doit s'exécuter après le filtre filter_html mais avant filter_autop.
Un mauvais ordre de filtres est la cause la plus fréquente des media embeds qui disparaissent à la republication ou qui s'affichent en HTML brut.
Quels attributs autoriser sur drupal-media
La balise <drupal-media> utilisée par CKEditor 5 pour les embeds nécessite que ses attributs soient autorisés dans le filtre HTML du format. Les attributs indispensables : data-entity-type, data-entity-uuid, data-view-mode, data-align, data-caption. Sans eux, Drupal supprime la balise lors de l'enregistrement et le media disparaît.
Styles d'image responsive
Configurez des styles d'image responsive_image pour chaque contexte d'affichage utilisé dans les media embeds. Liez-les aux view modes que vous autorisez (par exemple : full, medium, thumbnail). Limitez les view modes disponibles dans la configuration de l'éditeur pour éviter qu'un éditeur choisisse un view mode non optimisé.
Les plugins CKEditor 5 : choisir avec intention
Les plugins indispensables pour un format éditorial
Le module ckeditor5 de Drupal Core active un ensemble de plugins par défaut. Pour un format éditorial standard, les plugins utiles sont : Bold, Italic, Link, LinkImage, List, ListProperties, Heading, BlockQuote, Code, Alignment, HorizontalLine, et SourceEditing pour les formats avancés uniquement.
Ce qu'il vaut mieux désactiver pour les non-techniques
Le plugin Table de CKEditor 5 permet de créer des tableaux complexes avec fusion de cellules. Pour des éditeurs non techniques, la gestion des tableaux mal formés génère des tickets de support récurrents. Désactivez-le dans les formats destinés aux contributeurs, ou limitez-le à des tableaux simples sans mise en forme personnalisée.
Le plugin SourceEditing contourne toutes les règles de la barre d'outils. Réservez-le aux formats assignés aux développeurs ou aux administrateurs de contenu confirmés.
Héritage de profils et déploiement multi-environnements
Une configuration, tous les environnements
La force du système de configuration Drupal est de garantir que le format de texte configuré en développement est exactement celui qui tourne en production. Exportez vos configurations (drush config:export) après chaque modification, committez-les dans Git, et déployez-les via drush config:import.
Cette pratique élimine les divergences de configuration entre environnements, source classique de comportements inexpliqués en production.
Config splits pour les rôles
Si vous avez des formats de texte différents selon les environnements (par exemple un format de débogage avec SourceEditing en staging mais pas en production), utilisez le module config_split. Il permet de définir des variantes de configuration par environnement, sans maintenir plusieurs branches Git pour la configuration.
Tests de régression éditoriaux
Pourquoi les migrations CKEditor 4 vers 5 cassent des contenus
CKEditor 4 et CKEditor 5 ont des schémas HTML différents. La migration automatique fournie par Drupal couvre les cas courants, mais certains contenus produits par des plugins tiers CKEditor 4 peuvent sortir du processus de migration avec un HTML invalide ou tronqué.
La commande drush ckeditor5:check-upgrade-messages (disponible dans le module ckeditor5 de Drupal Core depuis Drupal 9.4) indique les formats de texte qui présentent des incompatibilités et propose des migrations de configuration.
Construire un corpus de test
Avant toute migration de format de texte, constituez un corpus de dix à quinze nœuds représentatifs : un article avec tableau, un avec media embed, un avec des listes imbriquées, un avec du code, un copié depuis Word. Ces nœuds servent de référence : exportez leur HTML rendu avant la migration, comparez-le après. Une différence est un bug à traiter.
Les tests à automatiser
Les tests fonctionnels Drupal (PHPUnit + Nightwatch) permettent d'automatiser la vérification du rendu éditorial. Un test simple ouvre un nœud du corpus, vérifie que les media embeds s'affichent, que les liens fonctionnent et que les styles appliqués sont présents dans le HTML final.
Migration des contenus existants
Identifier les contenus à risque
Le module contribué ckeditor5_migration_utils apporte des utilitaires pour repérer les contenus dont le HTML nécessite une migration avant passage à CKEditor 5. Il analyse les contenus existants et remonte les types de balises ou d'attributs incompatibles avec la nouvelle configuration.
C'est un outil de diagnostic, pas de correction automatique : les corrections doivent être validées au cas par cas avant d'être déployées en masse.
La stratégie de migration recommandée
Migrez format par format, pas tout d'un coup. Commencez par les formats les moins utilisés ou les plus simples. Validez chaque migration sur un environnement de staging avant de la déployer. Gardez une sauvegarde de la base de données avant chaque migration de format : les comportements de migration peuvent différer selon le volume et la diversité des contenus.
Réduire les retours support : trois décisions qui changent l'usage
Limiter les formats disponibles par rôle
Drupal permet d'assigner des formats de texte à des rôles via les permissions. Si un contributeur n'a accès qu'à un format bien configuré, il ne peut pas contourner les règles en changeant de format dans l'interface d'édition. C'est plus efficace qu'une documentation que personne ne lit.
Documenter dans l'éditeur
CKEditor 5 supporte les placeholder sur les champs de saisie et des guides contextuels via des plugins. Ces mécanismes permettent d'indiquer aux éditeurs ce qui est attendu dans chaque champ, directement dans l'interface. Un guide intégré à l'outil est suivi ; un guide dans Confluence ne l'est pas.
Former sur trois points précis
Les trois points qui réduisent les tickets de support : comment coller depuis Word proprement (Maj+Ctrl+V ou le bouton « Coller sans formatage »), comment insérer un media via la médiathèque et non par glisser-déposer direct, et quand utiliser la vue Source et quand s'en abstenir.
Ce qu'une configuration bien posée change au quotidien
Une configuration CKEditor 5 fiable n'est pas le résultat d'un paramétrage ponctuel. C'est une décision d'architecture éditoriale qui se traduit en configuration de code, se déploie par le système de configuration Drupal et se vérifie par des tests. Les équipes qui l'abordent comme un chantier de gouvernance (rôles, formats, filtres, tests) réduisent leurs retours support et gagnent en productivité éditoriale sur la durée.
Si votre organisation migre vers Drupal 11 ou reprend une configuration héritée de Drupal 9, un diagnostic de vos formats de texte et de vos contenus existants évite les mauvaises surprises en production.
Un projet web en tête ?
Commençons par un diagnostic : ce qui vous ralentit, et par où commencer.
Demander un diagnostic