Handbuch · 8

Dateien und Bilder

Hochladen und ordnen

Unter Dateien: Dateien per Drag & Drop in die Fläche ziehen oder Hochladen klicken (bis 64 MB pro Datei). Ordner dienen nur der Übersicht – verschieben oder umbenennen ändert die URL einer Datei nie. Zum Verschieben eine Datei auf einen Ordner links ziehen.

Rechts zu jeder Datei: Name, Alt-Text, Maße, Varianten, URL kopieren, Template-Tag kopieren, Löschen.

Aufräumen

Nach erneuten Importen oder Umbauten bleiben oft Bilder und CSS/JS-Dateien übrig, die nichts mehr verwendet. Aufräumen… (unter Dateien und unter CSS & JS) listet sie auf – Bilder mit Vorschau, alles vorausgewählt. Abwählen, was bleiben soll, dann Ausgewählte löschen; vorher kommt eine Rückfrage. Gelöscht wird endgültig, samt Bildvarianten und WebP-Fassungen.

Als verwendet gilt eine Datei, wenn Seiten (HTML, Head, SEO-Felder), Snippets, CSS/JS, Collection-Einträge, Workflows, Pens oder REST-Quellen auf sie verweisen – über ihre Adresse (auch eine Bildvariante oder WebP-Fassung), über image(ID)/file(ID), ein Bild- oder Datei-Feld, als Website-Icon oder Vorschaubild. CSS/JS gilt als verwendet, wenn es an einer Seite hängt oder per asset_url(ID) eingebunden ist; ein ungenutztes Stylesheet zählt nicht als Verwendung der Bilder darin. Kurz vor dem Löschen prüft der Server noch einmal und lässt alles stehen, was inzwischen verwendet wird.

Nicht erkennbar sind Verweise von außen (andere Websites, Newsletter, die direkt auf /media/… zeigen) und aus alten Versionen in der Versionshistorie – wer eine Seite auf einen alten Stand zurücksetzt, findet dort gelöschte Bilder nicht mehr. Im Zweifel abwählen.

Bildvarianten und `srcset`

Für JPEG und PNG erzeugt IllusionCMS beim Hochladen automatisch verkleinerte Fassungen mit 320, 640, 960, 1280 und 1920 px Breite (nur Breiten kleiner als das Original). Browser laden damit nur so viel Bild, wie sie brauchen. GIF, WebP und SVG werden unverändert gespeichert.

So kommen Bilder auf die Seite:

Button Bild im Editor – fügt ein <img> mit srcset, sizes, Breite/Höhe, Alt-Text und loading="lazy" ein; bei JPEG/PNG in einem <picture> mit WebP-Fassungen (siehe unten).

Template-Tag – bleibt aktuell, wenn sich Alt-Text oder Datei ändern:

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

Datei-Infos für eigene Konstruktionen:

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

sizes richtig setzen: Der Wert sagt dem Browser, wie breit das Bild auf der Seite dargestellt wird. 100vw für volle Breite, (min-width: 960px) 50vw, 100vw für ein Bild, das ab Desktop halb so breit ist. Im Bild-Dialog gibt es Vorlagen.

Alt-Texte beschreiben das Bild für Screenreader und Suchmaschinen. Pflege sie in der Dateiverwaltung – image() übernimmt sie automatisch.

WebP und Größen per URL

Zu jedem JPEG und PNG – Original und allen Varianten – gibt es automatisch eine WebP-Fassung, meist etwa halb so groß. image() und der Bild-Dialog setzen das Bild deshalb in ein <picture>: Browser mit WebP-Unterstützung (alle aktuellen) laden die WebP-Datei, alle anderen das gewohnte <img>:

<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>

Die WebP-Datei heißt wie das Bild mit angehängtem .webp und entsteht beim ersten Abruf (einmalig ein Bruchteil einer Sekunde), danach liegt sie als Datei neben dem Original – auch für bereits vorhandene Bilder, ohne dass du etwas tun musst. Wird ein Bild ersetzt (Re-Import), entsteht sie neu.

Für eigenes HTML und CSS gibt es URL-Parameter:

URL	liefert
`/media/…/foto.jpg?w=500`	die kleinste Variante mit mindestens 500 px Breite (hier 640 px), sonst das Original
`/media/…/foto.jpg?format=webp`	die WebP-Fassung des Originals
`/media/…/foto.jpg?w=500&format=webp`	beides kombiniert

w wählt immer eine der festen Breiten (320, 640, 960, 1280, 1920) – beliebige Größen werden nicht erzeugt, damit niemand den Speicher füllen kann. In file() steht das WebP-srcset unter .webp_srcset. Der statische Export enthält die verwendeten WebP-Dateien.

Private Dateien

Eine Datei kann privat sein: Besucher der Website bekommen sie nicht zu sehen – /media/… antwortet ihnen mit „nicht gefunden“ (404), als gäbe es die Datei nicht. Das gilt für das Original, alle Bildvarianten und WebP-Fassungen. Sehen dürfen sie:

Angemeldete – im Admin (Sitzung) und mit einem API-Token, auch mit Lese-Token (Authorization: Bearer … oder ?token=…),
wer einen signierten Link hat.

Gedacht ist das für vertrauliche PDFs, Entwürfe oder Material, das du Kunden per Link schickst.

Umschalten: Unter Dateien die Datei anklicken und rechts den Schalter Privat setzen – das wirkt sofort. Gleich privat hochladen: Haken Privat neben Hochladen setzen. Private Dateien tragen im Raster ein Schloss mit „Privat“; in den Auswahl-Dialogen (Bild einfügen, Datei verlinken) steht bei ihnen ein Hinweis.

Signierte Links: Bei einer privaten Datei unter dem Schalter die Gültigkeit wählen (1 Stunde, 1 Tag, 7 Tage, 30 Tage) und Link kopieren klicken. Die vollständige Adresse liegt dann in der Zwischenablage, die Meldung nennt das Ablaufdatum. Der Link sieht so aus: /media/2026/10/angebot-ab12.pdf?exp=…&sig=… – er gilt für die Datei samt Varianten und WebP-Fassungen und lässt sich weder verlängern noch auf andere Dateien übertragen. Einzelne Links lassen sich nicht zurückziehen: Signaturen bleiben bis zum Ablauf gültig, auch wenn du die Datei zwischendurch öffentlich und wieder privat schaltest. Wähle deshalb eine kurze Gültigkeit. Antworten auf private Dateien werden nicht zwischengespeichert (Cache-Control: private, no-store) und nicht indexiert (X-Robots-Tag: noindex), Downloads zählen nicht in der Statistik.

Vorschau: In der Vorschau im Seiten-Editor, bei ?preview=1 und in Vorschau-Links erscheinen private Bilder trotzdem – image(), file() (.url, .srcset, .webp_srcset), Website-Icon und Vorschaubild liefern dort signierte Adressen (etwa ein bis zwei Stunden gültig). Auf der Live-Seite bleiben die Adressen unsigniert, Besucher sehen das Bild also nicht. file(ID).private sagt, ob eine Datei privat ist, etwa um einen Link nur für öffentliche Dateien auszugeben:

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

Grenze: Nur Adressen aus image()/file() werden signiert. Von Hand ins HTML geschriebene Pfade (<img src="/media/…">, auch aus dem Bild-Dialog ohne Als Template-Tag einfügen) bleiben, wie sie sind – in der Vorschau fehlt das Bild dann. Für private Bilder deshalb das Template-Tag verwenden (der Bild-Dialog wählt es bei privaten Dateien vor). Der statische Export lässt private Dateien immer weg.