Manual · 8

Archivos e imágenes

Subir y organizar

En Archivos: arrastra los archivos a la zona o haz clic en Subir (hasta 64 MB por archivo). Las carpetas solo sirven para organizar: mover o renombrar nunca cambia la URL de un archivo. Para mover un archivo, arrástralo a una carpeta de la izquierda.

A la derecha, para cada archivo: nombre, texto alternativo, dimensiones, variantes, copiar URL, copiar etiqueta de template, eliminar.

Limpiar

Tras nuevas importaciones o reformas suelen quedar imágenes y archivos CSS/JS que ya no usa nada. Limpiar… (en Archivos y en CSS & JS) los lista: las imágenes con vista previa, todo preseleccionado. Desmarca lo que deba quedarse y luego Eliminar seleccionados; antes se pide confirmación. Se elimina definitivamente, junto con las variantes de imagen y las versiones WebP.

Un archivo se considera usado si páginas (HTML, Head, campos SEO), Snippets, CSS/JS, entradas de Collection, Workflows, Pens o fuentes REST hacen referencia a él: mediante su dirección (también una variante de imagen o versión WebP), mediante image(ID)/file(ID), un campo de imagen o de archivo, o como icono del sitio web o imagen de vista previa. Un CSS/JS se considera usado si está asignado a una página o se incluye mediante asset_url(ID); una hoja de estilos sin usar no cuenta como uso de las imágenes que contiene. Justo antes de eliminar, el servidor vuelve a comprobarlo y deja todo lo que entretanto se esté usando.

No se pueden detectar las referencias desde fuera (otros sitios web, boletines que apuntan directamente a /media/…) ni las de versiones antiguas del historial: quien restaure una página a una versión antigua no encontrará allí las imágenes eliminadas. En caso de duda, desmarca.

Variantes de imagen y `srcset`

Para JPEG y PNG, IllusionCMS genera automáticamente al subirlos versiones reducidas de 320, 640, 960, 1280 y 1920 px de ancho (solo anchos menores que el original). Así, los navegadores cargan solo la imagen que necesitan. GIF, WebP y SVG se guardan sin cambios.

Así llegan las imágenes a la página:

Botón Imagen en el editor: inserta un <img> con srcset, sizes, ancho/alto, texto alternativo y loading="lazy"; en JPEG/PNG, dentro de un <picture> con versiones WebP (ver más abajo).

Etiqueta de template: se mantiene actualizada si cambian el texto alternativo o el archivo:

{{ image(12) }}
{{ image(12, "(min-width: 900px) 50vw, 100vw") }}
{{ image(12, "100vw", "hero-bild") }}

Información del archivo para construcciones propias:

{% with f=file(12) %}
  <div class="hero" style="background-image:url('{{ f.url }}')"></div>
{% endwith %}

Definir bien sizes: el valor le dice al navegador con qué ancho se muestra la imagen en la página. 100vw para el ancho completo, (min-width: 960px) 50vw, 100vw para una imagen que en escritorio ocupa la mitad del ancho. En el diálogo de imagen hay plantillas.

Los textos alternativos describen la imagen para lectores de pantalla y buscadores. Mantenlos en la gestión de archivos: image() los adopta automáticamente.

WebP y tamaños por URL

Para cada JPEG y PNG, el original y todas sus variantes, existe automáticamente una versión WebP, normalmente de aproximadamente la mitad de tamaño. Por eso, image() y el diálogo de imagen colocan la imagen dentro de un <picture>: los navegadores compatibles con WebP (todos los actuales) cargan el archivo WebP; los demás, el <img> habitual:

<picture>
  <source type="image/webp" srcset="/media/2026/10/foto-ab12-320w.jpg.webp 320w, …, /media/2026/10/foto-ab12.jpg.webp 1600w" sizes="100vw">
  <img src="/media/2026/10/foto-ab12.jpg" srcset="…" sizes="100vw" width="1600" height="900" alt="…" loading="lazy" decoding="async">
</picture>

El archivo WebP se llama como la imagen con .webp añadido y se crea en la primera solicitud (una sola vez, una fracción de segundo); después queda como archivo junto al original, también para imágenes ya existentes, sin que tengas que hacer nada. Si se reemplaza una imagen (reimportación), se vuelve a crear.

Para HTML y CSS propios hay parámetros de URL:

URL	devuelve
`/media/…/foto.jpg?w=500`	la variante más pequeña con al menos 500 px de ancho (aquí 640 px); si no, el original
`/media/…/foto.jpg?format=webp`	la versión WebP del original
`/media/…/foto.jpg?w=500&format=webp`	ambas cosas combinadas

w siempre elige uno de los anchos fijos (320, 640, 960, 1280, 1920): no se generan tamaños arbitrarios, para que nadie pueda llenar el almacenamiento. En file(), el srcset WebP está en .webp_srcset. La exportación estática contiene los archivos WebP usados.

Archivos privados

Un archivo puede ser privado: los visitantes del sitio no lo ven – /media/… les responde «no encontrado» (404), como si el archivo no existiera. Esto vale para el original, todas las variantes de imagen y las versiones WebP. Pueden verlo:

los usuarios con sesión iniciada – en el admin (sesión) y con un token de API, también de solo lectura (Authorization: Bearer … o ?token=…),
quien tenga un enlace firmado.

Está pensado para PDF confidenciales, borradores o material que envías a clientes mediante un enlace.

Cambiar: en Archivos, haz clic en el archivo y activa Privado a la derecha; el efecto es inmediato. Para subirlo directamente como privado, marca Privado junto a Subir. Los archivos privados muestran en la cuadrícula un candado con «Privado»; los diálogos de selección (insertar imagen, enlazar archivo) muestran un aviso para ellos.

Enlaces firmados: para un archivo privado, elige la validez debajo del interruptor (1 hora, 1 día, 7 días, 30 días) y haz clic en Copiar enlace. La dirección completa queda en el portapapeles y el mensaje indica la fecha de caducidad. El enlace tiene este aspecto: /media/2026/10/oferta-ab12.pdf?exp=…&sig=…; vale para el archivo con sus variantes y versiones WebP y no se puede prolongar ni transferir a otros archivos. Los enlaces no se pueden revocar uno a uno: las firmas siguen siendo válidas hasta que caducan, aunque entretanto hagas el archivo público y luego privado de nuevo. Por eso, elige una validez corta. Las respuestas de archivos privados no se guardan en caché (Cache-Control: private, no-store) ni se indexan (X-Robots-Tag: noindex), y las descargas no cuentan en las estadísticas.

Vista previa: en la vista previa del editor de páginas, con ?preview=1 y en los enlaces de vista previa, las imágenes privadas aparecen igualmente: image(), file() (.url, .srcset, .webp_srcset), el icono del sitio y la imagen de vista previa devuelven allí direcciones firmadas (válidas entre una y dos horas aproximadamente). En la página publicada las direcciones quedan sin firmar, así que los visitantes no ven la imagen. file(ID).private indica si un archivo es privado, por ejemplo para mostrar un enlace solo para archivos públicos:

{% with f=file(12) %}{% if not f.private %}<a href="{{ f.url }}">{{ f.name }}</a>{% endif %}{% endwith %}

Límite: solo se firman las direcciones de image()/file(). Las rutas escritas a mano en el HTML (<img src="/media/…">, también desde el diálogo de imagen sin Insertar como etiqueta de template) se quedan como están; en la vista previa falta entonces la imagen. Para imágenes privadas usa la etiqueta de template (el diálogo de imagen la preselecciona para archivos privados). La exportación estática siempre omite los archivos privados.