Ir al contenido

Texto enriquecido

El campo richText es un editor con formato —negrita, subrayado, títulos, listas (también de tareas), enlaces, citas, código e imágenes— que escribe quien usa el panel. Lo que se guarda es el árbol de nodos del editor, en JSON, y no markdown ni HTML. Tu sitio lo pinta con <RichText>, en el servidor, sin que la página descargue ningún editor.

Esta guía va de declarar el campo a migrar lo que ya tenías en markdown. La referencia de cada export y de cada nodo está en Referencia del texto enriquecido.

Usa richText para un texto que tiene formato dentro del propio texto: un artículo con subtítulos, negritas, un par de enlaces y una imagen entre párrafos.

  • Si el texto no lleva formato, o es una línea, sigue con text.
  • Si quien escribe ya trabaja en markdown y quieres que lo siga haciendo, sigue con textarea y convierte tú el markdown en tu plantilla, como en Tu primera colección.
  • Si son datos con forma a medida, es json.

El content de la demo es el ejemplo completo. Es el bloque de apps/demo/cms.config.ts tal cual:

cms.config.ts
{
name: 'content',
type: 'richText',
label: 'Contenido',
admin: { description: 'Texto con formato. Se guarda como árbol JSON, no como HTML' },
features: [
'bold',
'italic',
'strikethrough',
'underline',
'inlineCode',
'heading',
'list',
'link',
'quote',
'codeBlock',
'hr',
'upload',
'image',
],
},

features dice qué puede escribir el editor. Cada feature activa añade su botón en la barra, su atajo y su regla de pegado, y el servidor rechaza cualquier nodo que no esté activo. Son estas trece:

Feature Qué habilita en el editor Qué se guarda
bold Negrita, con Ctrl/Cmd+B Marca de texto strong
italic Cursiva, con Ctrl/Cmd+I Marca de texto em
strikethrough Tachado Marca de texto s
underline Subrayado, con Ctrl/Cmd+U Marca de texto u
inlineCode Código en línea Marca de texto code
heading Títulos de nivel 1 a 6 Nodo heading con tag de h1 a h6
list Listas con viñetas, numeradas y de tareas Nodos list y listitem; en una lista de tareas, listType check y checked en cada elemento
link Enlaces, con Ctrl/Cmd+K Nodo link con su url
quote Cita en bloque Nodo quote
codeBlock Bloque de código Nodo code
hr Línea horizontal Nodo horizontalrule
upload Imagen de la biblioteca de medios Nodo upload: el slug de la colección y el id
image Imagen por dirección https Nodo image: la src y el alt

Sin features, el campo activa todas excepto upload e image. La razón es la misma para las dos: no cambian el texto, crean una dependencia. upload ata el contenido a tu biblioteca de medios, e image depende de un servidor que no controlas. Quien quiere imágenes en el texto las pide por nombre.

Un campo richText tiene tres opciones más, además de las comunes de todos los campos:

  • uploadTo: el slug de la colección de la que salen las imágenes de la biblioteca. Por defecto es ssd. Si la indicas y esa colección no existe o no declara upload, falla al arrancar. La demo no lo pone.
  • maxSize: el tamaño máximo del JSON en bytes. Por defecto son 512 KB. Ver Límites.
  • required: con true se rechaza un árbol sin contenido. Cuentan el texto que no sea solo espacios ni caracteres invisibles, también dentro de un bloque de código, y los nodos upload, image y hr, tengan o no texto. Un párrafo vacío no cuenta.

Un documento creado sin ese campo se guarda con un árbol vacío: un único párrafo sin texto. En el panel pasa lo mismo con un campo opcional que se deja vacío, al crear o al vaciarlo después, así que se guarda el árbol vacío y no null. Así <RichText> siempre recibe algo que pintar. Por la API, un campo que no envías toma ese mismo árbol al crear; uno que envías como null se guarda como null, y <RichText> no pinta nada con él. Un campo required vacío se rechaza con el error de obligatorio.

En TypeScript el campo sale como unknown, igual que json. Se lo pasas tal cual a <RichText>.

Hay dos formas de meter una imagen, y no se mezclan.

El botón Insertar imagen de la biblioteca abre un selector de la biblioteca. Muestra solo imágenes y busca por nombre de fichero. El nodo que se guarda es { relationTo, value }: el slug de la colección y el id del medio, nunca una URL. Así, si cambias la ruta de tus ficheros, las imágenes del texto siguen funcionando.

Con la demo, la imagen sale de ssd sin declarar nada más. Cuando la página renderiza el texto, busca la URL del medio por su id con Astro.locals.cms, y eso tiene dos consecuencias:

  • La página tiene que leer con la API local, así que lleva export const prerender = false, como la página del post de la demo. En una página prerenderizada no hay Astro.locals.cms, y las imágenes de la biblioteca no salen. El resto del texto sí.
  • Si el medio ya no existe, su nodo no renderiza nada. La página no se rompe.

Si indicas uploadTo, el selector y el nodo apuntan a esa colección. Al guardar, el servidor rechaza un nodo upload cuyo relationTo no sea esa colección: el mensaje dice a qué colección apunta el nodo y cuál admite el campo. Así, por la API tampoco se puede apuntar a otra. Y al renderizar, <RichText> busca el medio en la colección cuyo slug aparece en el nodo, siempre que esa colección declare upload.

El botón Insertar imagen por dirección pide una dirección que empiece por https:// y un texto alternativo obligatorio. Antes de insertarla, un aviso dice que la imagen depende de un tercero: si su servidor deja de servirla, tu texto la pierde.

El nodo guarda la src tal como la escribiste, sin descargarla ni copiarla a tu biblioteca. Al renderizar sale como <img loading="lazy" referrerpolicy="no-referrer">, así que el navegador de tus lectores pide la imagen directamente al tercero.

Escribir ![texto](https://...) a mano en el editor no crea una imagen. El atajo de markdown se queda con el texto alternativo, y la imagen no aparece. Para una imagen, usa el botón.

El paquete exporta un componente, RichText. Se importa por su ruta y no tiene directiva client::

src/pages/posts/[slug].astro
import RichText from '@kevolution-co/cms/rich-text/RichText.astro'
<RichText value={post.content} />

Así lo usa la página de la demo. RichText acepta value, que es el valor del campo, y class, que pone en el div que envuelve el resultado. Si el valor es null o undefined, o si no hay nada que pintar, no sale ningún div.

Tres cosas que conviene saber:

  • Es solo de servidor. El componente no tiene script. Una página que pinta un richText no envía ni una línea de JavaScript para él, y el HTML del editor no llega al navegador.
  • Es tolerante. Un nodo que no conoce se pinta como sus hijos, si los tiene, y como nada si no. Nunca lanza. En desarrollo avisa por consola con el tipo del nodo; en producción no escribe nada.
  • Es una función pura del valor. Mismo árbol, mismo HTML, sin estado ni lecturas fuera del valor.

Para un correo, un resumen o cualquier sitio donde no hay página, usa las funciones de abajo:

import { renderToHtml, toPlainText } from '@kevolution-co/cms/rich-text'
const html = renderToHtml(post.content)
const resumen = toPlainText(post.content).slice(0, 160)

renderToHtml devuelve una cadena con el texto y los atributos escapados. Sin una función resolveUpload, los nodos upload no salen, porque no sabe qué URL darles. Para un correo, las rutas internas como /posts/... no son enlaces válidos: el cliente de correo no sabe a qué dominio pertenecen. Escribe la URL absoluta cuando la necesites. toPlainText devuelve los bloques separados por saltos de línea, y los elementos de una lista uno por línea. Las imágenes y las líneas horizontales no aportan texto.

El valor es el SerializedEditorState de Lexical tal cual, sin envoltorio: un objeto { root: { ... } } cuyos nodos llevan type y version. Es el formato que usa Lexical, con los dos nodos propios del paquete, upload e image. Lo que el editor no conoce, lo pinta el renderizador como hijos o como nada.

Se guarda así y no como markdown o HTML por tres razones:

  • Las imágenes de la biblioteca son por id. El markdown no tiene dónde poner un id de medio sin inventar una sintaxis, y el HTML guardaría la URL, que es justo lo que queremos evitar.
  • El HTML obliga a sanear al escribir. Con el árbol, el servidor valida una estructura cerrada: un nodo que no está en la tabla se rechaza, y no hay atributos que filtrar.
  • El árbol se renderiza igual en cualquier sitio. El mismo valor pinta una página, un correo o un resumen, sin cambiar lo que se guarda.

El formato es de cada nodo: cada uno lleva su version, y así se migra el contenido cuando cambie un nodo. Hoy no hay ninguna migración de ese tipo.

El JSON de un campo tiene que caber en una fila de D1, que admite 2 MB. Por eso maxSize vale 512 KB (524 288 bytes) por defecto. Un valor que pasa de maxSize se rechaza con 400 y el mensaje dice el tamaño recibido y el límite. Nada se trunca.

Para dar una idea de cuánto cabe, se midió el JSON de artículos de markdown convertidos con las features por defecto, de 1 000 a 25 000 palabras. Salen unos 18 bytes por palabra, y 512 KB dan para unas 29 000 palabras. El artículo de la medición tiene un 3 % de palabras en negrita o cursiva y un enlace cada 200 palabras. Si escribes con muchos enlaces o marcas, el JSON pesa más por palabra; si escribes texto plano, pesa menos.

El paquete no migra nada solo, ni al arrancar ni con un comando. Si ya tienes markdown en un campo textarea, lo conviertes tú con dos funciones de @kevolution-co/cms/rich-text/convert: markdownToLexical y lexicalToMarkdown.

Este script lee un JSON con los posts que tienen markdown en body, y escribe otro con el árbol de cada uno en content y el markdown que sale de vuelta, para que lo revises. Lo corres con Node 24, que quita los tipos sin compilar:

migrar-markdown.ts
import { readFile, writeFile } from 'node:fs/promises'
import { lexicalToMarkdown, markdownToLexical } from '@kevolution-co/cms/rich-text/convert'
type Row = { id: string; body: string | null }
const rows: Row[] = JSON.parse(await readFile('posts.json', 'utf8'))
const out = rows.map((row) => {
// Sin opciones: las features por defecto, todas menos upload e image. Un body vacío da un árbol vacío
const content = markdownToLexical(row.body ?? '')
return {
id: row.id,
content,
// Para revisar: lo que vuelve a salir del árbol, no el original
revisar: lexicalToMarkdown(content),
}
})
await writeFile('posts-richtext.json', JSON.stringify(out, null, 2))

El posts.json lo sacas tú de la base, con la herramienta que uses. Después, cada content se escribe con la API, con un PATCH por documento, como cualquier otro campo. El valor es el objeto tal cual, no una cadena.

Qué se normaliza al convertir, y qué se pierde:

Markdown Qué queda Por qué
- [ ] tarea y - [x] tarea Lista de tareas, con la tarea marcada o sin marcar Con la feature list
[texto](javascript:...) Solo el texto Un enlace que el validador no acepta pierde el enlace
![alt](url) Solo el texto alternativo Con las features por defecto no hay imagen. Si quieres imágenes, vuelve a insertarlas en el editor
Tablas Texto, con sus barras verticales No hay nodo de tabla
HTML en línea Texto No hay nodo para el HTML
Listas muy anidadas (desde el sexto nivel de listas) El texto de sus elementos, una línea por elemento, dentro del elemento que contenía la lista Un nivel de lista tan hondo no tiene forma útil en el editor

Y al revés, lexicalToMarkdown no reproduce el markdown original letra a letra. Las barras, los asteriscos y los guiones se escapan como hace falta, y las listas anidadas usan la sangría de su marcador. Lo que sí se conserva es el contenido de las features: negrita, cursiva, tachado, código, títulos, listas (las de tareas como - [ ] y - [x]), enlaces, citas, bloques de código y líneas horizontales. El subrayado no tiene sintaxis en markdown, así que sale solo su texto. Los nodos upload salen como nada en el markdown, porque el módulo no conoce la URL del medio y no la inventa. Esto es lo que se cumple al hacer ida y vuelta: el texto y sus marcas, no la forma exacta de escribirlos.

El editor trabaja sobre el árbol: lo que ves en el área de escritura es lo que se guarda, sin vista previa aparte.

La barra. Tiene un botón por cada feature activa, en el mismo orden: negrita, cursiva, tachado, subrayado, código en línea, un menú de encabezado (párrafo o encabezado 1 a 6), listas con viñetas, numeradas y de tareas, enlace, cita, bloque de código, línea horizontal, deshacer, rehacer y, si las pides, los dos botones de imagen. Los botones que tienen atajo lo enseñan al pasar el ratón. Si el campo es de solo lectura, la barra entera queda deshabilitada.

Los atajos. Solo funcionan con la feature correspondiente:

Atajo Qué hace Condición
Ctrl/Cmd+B Negrita bold
Ctrl/Cmd+I Cursiva italic
Ctrl/Cmd+U Subrayado underline
Ctrl/Cmd+K Abre el editor de enlace link
Ctrl/Cmd+Z Deshacer siempre
Ctrl/Cmd+Shift+Z Rehacer siempre

Ctrl/Cmd+B, Ctrl/Cmd+I y Ctrl/Cmd+U no hacen nada si su feature está apagada: el editor no deja que el navegador los aplique por su cuenta.

Los atajos de markdown. Al escribir, el editor convierte estas sintaxis, pero solo las de las features activas. Las demás se quedan como texto:

Escribes Obtienes Feature
# hasta ###### Encabezado de nivel 1 a 6 heading
- Lista con viñetas list
[ ] o [x] Lista de tareas, sin marcar o con la primera tarea marcada list
1. Lista numerada list
> Cita quote
``` Bloque de código codeBlock
--- Línea horizontal hr
`código` Código en línea inlineCode
**texto**, *texto* Negrita, cursiva bold, italic
~~texto~~ Tachado strikethrough
[texto](/ruta) Enlace link

El número de # del atajo es el nivel del encabezado. Con siete o más # la línea se queda como texto.

Las listas de tareas. El botón Lista de tareas de la barra, o el atajo [ ] (o [x] para la primera tarea ya marcada) al empezar una línea, crea una lista de tareas. Cada elemento lleva una casilla que se marca con un clic, o con el teclado: con el cursor al inicio del elemento, la flecha izquierda pone el foco en la casilla y Espacio la alterna. El estado queda en el JSON como checked, y la página pública pinta la casilla marcada o sin marcar, deshabilitada. Pulsar el botón otra vez devuelve la lista a párrafos.

0. empieza una lista numerada en 0, si la línea no sigue a otra lista numerada: en ese caso el número se ignora y la lista continúa. Un - o un 1. con sangría que llevaría la lista a un sexto nivel no se convierte, y la línea queda como texto.

El enlace. El botón de enlace y Ctrl/Cmd+K abren una caja con la dirección. Antes de comprobarla, quita los espacios de los extremos y cambia cada espacio interior por %20: /sobre nosotros se guarda como /sobre%20nosotros. En un tel: quita todos los espacios, así que tel:+34 600 000 000 se guarda como tel:+34600000000. Una dirección que sigue sin ser válida se rechaza con un aviso, y si tenía espacios, el aviso lo dice, porque %20 no la arregla. Quitar el enlace deja el texto.

La accesibilidad. El área de escritura es un textbox multilínea con el label del campo, y declara si es obligatorio o de solo lectura. La barra es un toolbar que se recorre con las flechas izquierda y derecha, con Inicio y Fin; solo un botón de la barra entra en el orden de tabulación. Cada botón tiene nombre accesible, y los botones de alternancia (negrita, cursiva, listas, cita…) exponen su estado con aria-pressed. El menú de encabezado tiene nombre propio, «Encabezado», y sus opciones (párrafo y encabezado 1 a 6) son elementos de menú con estado marcado, no botones pulsados: el botón que lo abre no lleva aria-pressed.

La carga. El editor pesa lo suyo, así que se carga aparte. Solo se descarga al abrir un documento que tiene un campo richText, y las demás pantallas del panel no lo cargan. Mientras llega, el campo muestra un esqueleto con el mismo alto.

Al pegar o arrastrar contenido, el editor toma el HTML del portapapeles si lo hay, y si no, el texto plano. El HTML pasa por un filtro que construye nodos nuevos, así que no entra nada de lo que no está en la lista: clases, estilos en línea, colores, fuentes, tablas, scripts, formularios, iframes ni SVG. El formato interno de Lexical que trae el portapapeles de otro editor nunca se importa: entra texto plano o HTML limpio.

Lo que sobrevive, según las features activas:

  • Negrita, cursiva, subrayado y tachado. Por las etiquetas strong, b, em, i, u, s, del y strike, y por el estilo en línea que escriben Word y Google Docs: font-weight, font-style y text-decoration con underline o line-through. El underline de un texto dentro de un enlace no cuenta: así se dibuja un enlace, no es subrayado de verdad. Un b con font-weight: normal no es negrita, que es como Google Docs envuelve el texto. Si la feature está apagada, el texto se pega sin la marca.
  • Títulos. Los seis niveles, h1 a h6, se quedan como están. Sin la feature heading, son párrafos.
  • Enlaces. Solo se conserva el href, y solo si es una ruta interna, http, https, mailto o tel. Los demás pierden el enlace y conservan el texto.
  • Listas de tareas. Una lista cuyos elementos llevan una casilla (<input type="checkbox">, como en GitHub) o aria-checked (Google Docs y el propio editor al copiar) pasa a lista de tareas, con cada elemento marcado o sin marcar. Necesita la feature list; sin ella, son párrafos.
  • Imágenes. Un img con una src https pasa a nodo image con su alt, si la feature image está activa. En cualquier otro caso se descarta. El editor no descarga nada.
  • Tablas y el contenido de bloques. Una tabla se pega como texto: cada celda y cada fila quedan como párrafos. Lo que estaba dentro de un bloque no se pierde.
  • Listas, citas, código y líneas. ul y ol pasan a listas si la feature list está activa, y a párrafos si no. Lo mismo con blockquote, pre y hr y sus features. Las listas pegadas conservan cinco niveles de lista contados desde la raíz del documento (si pegas con el cursor ya dentro de una lista, cuentan los niveles que ya hay): desde el sexto, cada elemento pasa a una línea de texto dentro del elemento de la lista que lo contenía.

Si el filtro falla, el editor inserta el texto plano del portapapeles, así que no pierdes el texto.

Direcciones en texto plano. Si lo que pegas no trae HTML, cada dirección http:// o https:// del texto se convierte en un enlace a sí misma, si el campo tiene la feature link. La dirección no incluye el . o la , con que acaba una frase, ni un ) que ella misma no abrió: (mira https://ejemplo.dev/a). enlaza https://ejemplo.dev/a. No se enlaza una dirección de más de 2 048 caracteres. Tampoco se enlazan mailto:, javascript: ni un www. sin esquema: se quedan como texto. Con el cursor dentro de un enlace, de código en línea o de un bloque de código, la dirección entra como texto. Escribir una dirección a mano no la enlaza. El enlace pasa las mismas reglas de validación que cualquier otro.

Dentro de un bloque de código, lo que pegas entra como texto plano, sin párrafos ni formato. Si el portapapeles trae texto plano, se usa ese, con su sangría. Si solo trae HTML, la sangría se pierde, salvo la de los bloques pre que vengan en el HTML.

Tabuladores y arrastres. Un tabulador se guarda como carácter de tabulación dentro del texto, sin nodo propio. Arrastrar un texto dentro del propio editor lo copia en vez de moverlo, y el contenido entra en la posición del cursor, no en el punto donde lo soltaste.

Un nodo que el editor no conoce puede llegar de una versión más nueva del paquete, o de un script que escribió un valor a mano. Hay dos respuestas distintas, una por cada lado:

  • En la web pública, el renderizador lo tolera. Pinta sus hijos si los tiene, y nada si no. No lanza, y no rompe la página.
  • En el panel, el campo se abre en solo lectura con un aviso: «Este campo contiene un nodo «…» que el editor no reconoce». El resto del formulario sigue siendo editable, y al guardar el documento el campo no se envía, así que el valor guardado no se toca. Puedes editar el resto sin miedo a perder ese contenido.

Un nodo que sí conoce el editor pero que la feature del campo no permite, como un upload en un campo sin upload, no se marca como desconocido: el editor lo muestra como cualquier otro. El problema aparece al guardar, con el 400. Ver la solución de problemas.

Al guardar sale un 400 que dice «requiere la feature»

Sección titulada «Al guardar sale un 400 que dice «requiere la feature»»

Síntoma. El documento no se guarda, y el mensaje dice algo como root.children[2] usa el nodo "upload", que requiere la feature "upload" y este campo no la tiene.

Causa. El texto tiene un nodo que el campo no permite, casi siempre porque quitaste la feature de features después de escribir con ella.

Arreglo. Vuelve a añadir la feature al campo, o borra el elemento del texto. El mensaje dice la ruta del nodo, root.children[2], que es el tercer bloque del documento.

El documento tiene un encabezado de un nivel que no existe

Sección titulada «El documento tiene un encabezado de un nivel que no existe»

Síntoma. El 400 dice tiene tag "h7"; los válidos son h1, h2, h3, h4, h5 y h6.

Causa. El documento se escribió con un encabezado que no es de h1 a h6 desde fuera del CMS, por un script o una escritura directa en la base de datos. El CMS no lo crea, y la API lo rechaza.

Arreglo. Cambia el tag de ese encabezado a uno de h1 a h6 en el origen, y vuelve a escribir el documento.

Síntoma. ocupa N bytes y el límite es 524288 bytes.

Causa. El artículo tiene más de unas 29 000 palabras con las marcas típicas, o tiene muchas imágenes externas. Con las imágenes de la biblioteca el peso es pequeño; con muchas marcas pesa más.

Arreglo. Parte el texto, o sube maxSize del campo. Cuenta el total de la fila: D1 admite 2 MB por fila, con todos los campos del documento dentro.

La imagen de la biblioteca no sale en la página

Sección titulada «La imagen de la biblioteca no sale en la página»

Causa. Una de estas dos: la página está prerenderizada y no tiene Astro.locals.cms, o el medio ya no existe. En ambos casos el nodo no renderiza nada y el resto del texto sí.

Arreglo. Lleva export const prerender = false en la página, y comprueba que el medio existe en la biblioteca.

Síntoma. El campo muestra «Cargando el editor…» y no llega.

Causa. La descarga del fichero del editor falló.

Arreglo. Recarga la página. Si pasa siempre, mira en la consola del navegador qué fichero no se cargó.

Causa. La feature bold no está en features. Lo mismo con Ctrl+I y italic, y con Ctrl+U y underline.

Arreglo. Añade la feature, o usa el texto plano.

Pegar un documento de Word pierde las imágenes

Sección titulada «Pegar un documento de Word pierde las imágenes»

Causa. Una imagen cuya src no es https, como las data: que pega Word, se descarta siempre. Las https solo pasan si image está activa.

Arreglo. Pega solo el texto, o inserta la imagen con el botón de la biblioteca.