Validar contenido dentro de CKEditor 5 sin molestar a los editores
Cómo pasé de arreglar contenido a mano a prevenir errores de accesibilidad en CKEditor 5: avisos en vivo, bloqueos solo donde hace falta y CSS del editor.
- #drupal
- #ckeditor
- #accesibilidad
- #javascript
Después de varias rondas de pedidos de accesibilidad me di cuenta de algo un poco incómodo: la mayoría de los problemas no estaban en el código, sino en lo que escribían los editores. Imágenes sin alt (el texto alternativo que leen los lectores de pantalla), encabezados que saltan de H2 a H4 (no es un fallo estricto de WCAG, pero la guía de W3C recomienda evitarlo), o textos alternativos como “Image” o “foto1.jpg”.
Corregir eso a mano funciona una vez, pero dos meses después llega el mismo reporte. Así que el enfoque cambió: había que prevenir los errores dentro de CKEditor 5, el editor de texto que usan en Drupal, pero sin complicarle la vida a quien escribe. Aquí comparto tres casos de ese trabajo.
Primero, que el editor muestre lo que realmente hay #
Este empezó como un error reportado en un issue, no como un pedido de accesibilidad. Los editores veían que las listas no tenían viñetas ni números dentro del editor, aunque en el sitio publicado se veían bien. En otras palabras, el editor no mostraba lo que realmente se iba a publicar.

La misma lista en el editor, antes (izquierda) y después (derecha) del arreglo. El texto está pixelado.
No me costó mucho encontrar la causa.
Resultó que la hoja de estilos del editor quitaba el formato de todas las listas y luego volvía a dibujar las viñetas con ::before, pero solo dentro de una clase de tipografía que Drupal nunca aplica al área de edición. Se quitaba el formato, pero no se volvía a poner. Lo solucioné moviendo los estilos de las listas a un bloque reutilizable (un mixin) y aplicándolo también en .ck-content:
.typography,
.ck.ck-content {
@include typography-lists;
}
Comparé el CSS final del sitio antes y después, y era idéntico byte por byte. Lo que aprendí: si el editor no se parece al sitio, la gente deja de confiar en lo que ve.
Bloquear solo lo que es claramente un error #
En otro pedido la regla era image-alt: imágenes guardadas sin texto alternativo. En la base de datos había 342 imágenes así, repartidas en 57 páginas.
El cambio principal fue en el guardado, y la regla quedó así:
- Si una imagen no tiene
alt, no se puede guardar. El editor ve un mensaje que le pide agregarlo. - Las imágenes decorativas sí se permiten. Son las que tienen
alt="", que es lo que pone la opción de “imagen decorativa” de CKEditor 5 en Drupal. Es válido, porque los lectores de pantalla simplemente las saltan. En cambio, una imagen sin ningún atributoaltsí es un fallo de WCAG. - Los 12 caracteres son solo una recomendación. El mensaje sugiere usar al menos 12 caracteres y no empezar con “Imagen de”, pero no lo exige. Llegamos a probar una versión que sí lo obligaba y la quitamos.
Esto aplica a las imágenes dentro del texto, incluso dentro de Paragraphs anidados, y también a los campos de imagen.
¿Y las 342 que ya existían? No las llené todas con un script. Para las 38 imágenes de las páginas que marcó el escáner, un post_update agregó un texto alternativo escrito revisando cada imagen y su contexto, y lo dejé listo para revisión. El resto se corrige cuando alguien vuelve a editar ese contenido, porque ya no se puede guardar sin agregar el alt.
Un plugin de “content checks” #
Este fue el que más disfruté. Para el orden de los encabezados, en lugar de validar en el servidor, construí un plugin genérico para CKEditor 5 donde cada regla es un archivo pequeño. Lo pensé así para que se puedan agregar más reglas, y para que el plugin pueda crecer o cambiar de forma ordenada. Por ahora solo tiene la regla de encabezados, pero preferí dejar un plugin bien hecho que pueda crecer:
ContentChecks.addRule({
id: 'heading-order',
title: 'Los encabezados deben subir de a un nivel',
check(editor) {
// recorre el modelo y devuelve los encabezados que saltan niveles
},
});
Debajo de cada campo aparece una sección plegada, por ejemplo “Los encabezados deben subir de a un nivel (3)”. Al abrirla, cada problema es un botón que te lleva directamente a ese punto del editor. Al guardar, aparece un diálogo con las reglas que fallan en todos los campos y dos opciones: Revisar o Guardar de todas formas. Avisa, pero no bloquea. Además, el aviso para lectores de pantalla solo se actualiza cuando cambian los problemas, para que no se repita con cada tecla.
Lo que más trabajo me dio, sinceramente, fueron los detalles. Drupal tiene un formSingleSubmit que bloquea un segundo envío del formulario con los mismos datos, así que tomaba mi “Guardar de todas formas” como un envío duplicado. Paragraphs crea y elimina editores con AJAX cada vez que se agrega, abre o pliega un párrafo, incluso mientras alguien escribe. Y en modo código fuente, lo que escribes se queda en esa caja de texto y solo pasa al contenido del editor cuando sales de ese modo o cuando se piden los datos con getData(). Y puse cada regla en su propio try/catch, para que si una falla, las demás sigan funcionando.
Algunas cosas las dejé fuera a propósito. El primer encabezado de cada campo no se revisa, porque el nivel correcto depende de lo que la página muestra arriba, y los encabezados que vienen de las plantillas tampoco se incluyen.
Lo que me llevo #
Prevenir es mejor que limpiar después. Bloquea solo lo que es un error seguro, como un alt que no existe, y en lo demás limítate a avisar. Respeta los casos válidos, como alt="" en imágenes decorativas. El editor tiene que verse como el sitio. Y haz que el aviso lleve al problema: “tienes 3 errores” no ayuda mucho, pero un botón que te lleva al encabezado sí.