Anleitung 3: Bilder zu Beiträgen und Fragments hinzufügen
Originale ablegen, Titelbilder setzen, responsive Varianten vorbereiten und Dateien bereitstellen.
Auf dieser Seite
Dies ist Teil 3 von 8 der Einführung. Reihenfolge aller Tutorials · Konfiguration nach Feldern.
Du musst weder mehrere Bildgrößen von Hand erstellen noch Beitragslinks auf generierte Dateinamen umstellen. Lege Originale ab, verweise aus Beitrag oder Fragment darauf und lasse den lokalen Entwicklungsserver die responsiven Dateien vorbereiten.
Dieser Artikel verwendet die Standardordner src/ und public/ des Starters. Unterscheide zuerst die Verwendung:
| Verwendung | Wo angeben | Aktuelle Verarbeitung |
|---|---|---|
| Bilder im Beitragstext | Markdown-Bilder oder Bilder in MDX | Bisherige Markdown-/MDX-Verarbeitung; nicht Teil der folgenden persistenten Titelbildvorbereitung |
| Artikel-Titelbild | heroImage im frontmatter |
Responsive Dateien lokal vorbereiten; Liste und Detailseite verwenden dieselben Varianten |
| Fragment-Bilder | Markdown-Bilder, Referenzbilder oder HTML-img im Fragment |
Unterstützte lokale Bilder nutzen dieselben persistenten responsiven Dateien für Liste und Startseitenvorschau |
| Freigabe-Vorschaubild | ogImage des Beitrags oder site.ogImage |
Eigene Freigabebild-Logik, nicht gleich Titelbild-Thumbnails |
1. Originale im Projekt ablegen
Ein Bild für nur einen Beitrag kann neben dessen Datei liegen:
src/content/blog/de/
my-first-post.md
photo.jpg
cover.jpg
Für Fragments gilt dasselbe: Bilder können neben der Markdown-Datei liegen. Gemeinsam genutzte Bilder kannst du in public/images/ ablegen:
public/images/
shared-photo.jpg
fragments/
my-photo.png
Erstelle fehlende Ordner bei Bedarf. Verwende einfache englische Namen, Zahlen und Bindestriche, um Verwechslungen bei Großschreibung zu vermeiden. URL-Pfade verwenden /, keine Computerpfade wie C:\... oder D:\... und keine Backslashes. Auf Systemen mit Beachtung der Großschreibung sind Photo.jpg und photo.jpg nicht unbedingt dieselbe Datei.
Erhalte die Originale. Die später erzeugten WebP-Dateien sind Anzeigevarianten, kein Ersatz-Backup.
2. Bilder in den Beitragstext einfügen
Füge an der gewünschten Stelle in Markdown ein:

./photo.jpg ist relativ zur aktuellen Beitragsdatei und verweist im obigen Beispiel auf die Datei daneben. Für public-Dateien schreibe:

Das entspricht public/images/shared-photo.jpg. public gehört nicht in die URL. Der Text in eckigen Klammern ist der Alternativtext. Beschreibe den tatsächlichen Inhalt statt nur „Bild“ zu schreiben.
Normale Textbilder öffnen sich per Klick oder mit Fokus und Enter/Leertaste. Esc, Schließen oder Hintergrund schließen sie. Titelbilder und Bilder in Links oder Knöpfen nehmen nicht teil. Die Vergrößerung verwendet die bereits ausgewählte Browser-Quelle, lädt kein hochauflösenderes Original und ist keine Galerie.
prepare-covers komprimiert nicht automatisch jedes Textbild. Es verarbeitet den Titelbild-Quellpool, Titelbildreferenzen und lokale Fragment-Bilder. Normale public-Bilder im Artikeltext können weiterhin direkt das Original laden. Wähle passende Dateigrößen, besonders bei Screenshots mit mehreren MB.
3. Ein Artikel-Titelbild festlegen
Lege cover.jpg neben den Beitrag und ergänze oder ändere im vorhandenen frontmatter:
heroImage: ./cover.jpg
heroImage ist optional und muss bei Verwendung auf eine lokale Bilddatei im Projekt zeigen, nicht auf eine HTTPS-URL. /images/cover.jpg ist hier keine public-URL-Schreibweise; die Regeln unterscheiden sich von Textbildern.
Für zentrale Verwaltung neuer Titelbilder kannst du src/assets/blog/covers/originals/ verwenden. Liegt der Artikel unter src/content/blog/de/my-first-post.md und das Original unter src/assets/blog/covers/originals/my-cover.jpg, schreibe:
heroImage: ../../../assets/blog/covers/originals/my-cover.jpg
Das Titelbild wird nicht automatisch in den Text eingefügt. Es erscheint in Blog-/Taglisten und im Titelbildbereich der Detailseite. Das Layout kann sichtbare Bereiche zuschneiden, die erzeugten Bilddateien behalten jedoch ihr Seitenverhältnis. Der Prozess wählt keinen Personen- oder Motivfokus für dich.
new-post wählt automatische Titelbilder nur aus src/assets/blog/default-covers/. Ein Bild in covers/originals/ wird dadurch nicht automatisch gewählt; verweise selbst darauf.
4. Bilder in Fragments verwenden
Bei theme.fragments.enabled: false überspringen dev, build und prepare-covers/doctor Bildverweise im Fragments-Inhalt. Nur über diese Verweise aufgenommene Bilder benötigen dann keine Originale oder Ableitungen. Artikel-Cover-Verweise und die Pools src/assets/blog/default-covers/ und src/assets/blog/covers/originals/ werden weiterhin vorbereitet und geprüft, auch bei ausschließlich für Fragments verwendeten Bildern. Dateien bleiben erhalten; erneutes Aktivieren setzt die Fragments-Verarbeitung fort.
Versionshinweis: Bildisolierung bei deaktivierten Fragments erfordert mindestens 0.36.1 und fehlt in 0.36.0. Setze dieses Verhalten in älteren Versionen nicht voraus.
Lege das Original unter public/images/fragments/my-photo.png ab und schreibe im vorhandenen Fragment:

Alternativ lege photo.png daneben und verwende . Nur das Ablegen eines Bilds in public startet keinen allgemeinen Bildbibliothek-Scan; es muss tatsächlich in einem Fragment referenziert sein.
Referenzbilder werden ebenfalls unterstützt:
![Bildbeschreibung][photo]
[photo]: /images/fragments/my-photo.png
Für manuelle Maße kannst du HTML nutzen:
<img src="/images/fragments/my-photo.png" alt="Bildbeschreibung" width="640" height="360" />
Die Maße sind Beispiele. Setze das tatsächliche Seitenverhältnis. Bei unterstützten lokalen Bildern ergänzt der Prozess fehlende Breite und Höhe. Vorhandene Maße bleiben bestehen; fehlt nur eine Dimension, wird sie aus dem Originalverhältnis berechnet. Falsche vorhandene Maße werden nicht automatisch korrigiert.
Das erste Bild jeder Fragment-Listenseite lädt standardmäßig bevorzugt, weitere Bilder und Startseiten-Thumbnails lazy. Die Startseite zeigt nur eine höhenbegrenzte Vorschau mit abgeschnittenem Überhang, keinen vollständigen Bildbetrachter. Ein Kartenklick führt zum Originalfragment. Erstellung, stabile IDs und Kommentare erklärt Ein Fragment veröffentlichen.
5. Responsive Dateien lokal vorbereiten
Nach der ersten Bildreferenz oder dem Ersetzen eines Originals starte im Projektstamm den lokalen Entwicklungsserver:
npm run dev
Normale Aufrufe von npm run dev, npm run build und npm run doctor, auch in CI, bereiten fehlende, veraltete oder veränderte Varianten automatisch vor. dev reagiert außerdem auf Änderungen relevanter Quellen und Referenzen. Wenn du nur Bilder vorbereiten willst, stoppe dev und führe aus:
npx @anglefeint/astro-theme prepare-covers
Für reine Prüfung ohne Nachgenerieren:
npx @anglefeint/astro-theme prepare-covers --check
Nicht jedes Mal werden alle Bilder neu kodiert. Hashes von Originalen, Verarbeitungsregeln und Ausgaben bestimmen die Wiederverwendung. Geänderte Originale aktualisieren ihre Varianten; einzelne fehlende oder veränderte Ausgaben werden gezielt repariert. Ändere Manifest oder generierte Dateinamen nicht von Hand und trage generierte URLs nicht in Beiträge ein.
Aktuelle Regeln:
- Statische Rasterbilder erzeugen WebP mit Qualität 80. Das ist ein verlustbehaftetes Kodierungsziel, keine Garantie identischer Pixel.
- Kandidatenbreiten sind 400, 640, 800, 960 und 1200px. Je nach Original bleiben passende Größen und nötigenfalls die Quellbreite bis 1200px. Kleine Bilder werden nicht vergrößert.
- EXIF-Ausrichtung wird berücksichtigt, das Seitenverhältnis bleibt erhalten. Es entstehen keine anders komponierten Zuschnitte.
- SVG und Mehrbild-Animationen behalten ihr Format. Ein GIF mit nur einem Bild kann statisch verarbeitet werden; die Erweiterung allein entscheidet nicht.
- Standard-Titelbildpool, originals-Pool und tatsächliche Referenzen definieren den Umfang. Nicht alle public-Bilder werden umgewandelt.
Der Browser wählt anhand von srcset, sizes, Bildschirm und Pixeldichte. Nutzer brauchen keine Größenordner zu pflegen. Da die größte Variante 1200px hat, sind auf großen Displays mit hoher Pixeldichte nicht immer Originaldetails garantiert.
6. Welche Dateien committen und wie bereitstellen?
Nach Vorbereitung liegen die Dateien hier:
src/assets/blog/covers/
originals/ # Falls dieses Verzeichnis für Originale verwendet wird
manifest.json # Quelle, Abmessungen, Verarbeitungsregeln und Ausgabe-Hashes
generated/ # Persistente responsive Dateien
Committe Artikel- oder Fragment-Markdown und neue oder ersetzte Originalbilder. Manifest und generated-Dateien im Git erleichtern die Wiederverwendung; fehlende Varianten erzeugt build automatisch. Die automatische Vorbereitung erstellt keine Git-Commits.
Originale in public oder neben Artikeln musst du ebenfalls dort committen, nicht nur originals. Auch Fragment-Varianten liegen im Ordner blog/covers.
Stoppe vor Veröffentlichung dev und führe lokal npm run doctor aus. Danach kannst du mit npm run preview den Build ansehen. doctor enthält den Build bereits; ein sofortiger weiterer build ist unnötig. Die Hosting-Plattform verwendet weiterhin npm run build und das Ausgabeverzeichnis dist; veröffentliche dessen gesamten Inhalt.
Normale Aufrufe von dev, build und doctor, auch in CI, verwenden korrekte Bildvarianten wieder und ergänzen oder reparieren fehlende, veraltete oder veränderte Dateien automatisch. Committe Inhalte und referenzierte Originalbilder. Das Committen von src/assets/blog/covers/manifest.json und generated/ wird zur Wiederverwendung empfohlen, ist aber keine Voraussetzung für die automatische Vorbereitung. Fehlende Originale, unsichere Pfade und ungültige Eingaben führen weiterhin zu Fehlern. Dies setzt keinen erhaltenen Bildcache der Hosting-Plattform voraus.
Versionshinweis: Die automatische Bildvorbereitung bei normalen Builds und doctor in CI erfordert mindestens 0.36.2. Führe mit 0.36.1 zuerst dev oder prepare-covers aus, um Bildvarianten vorzubereiten. Explizites prepare-covers --check und Konfigurations-Sync bleiben schreibgeschützt.
Verwendete Varianten werden nach _blog-covers/ im Build kopiert. Lade nicht nur HTML hoch und lasse diesen Ordner nicht aus. Alte ungenutzte generated-Dateien werden nicht automatisch entfernt. Prüfe Referenzen vor einer Bereinigung und lösche keine benötigten Originale.
Unterschiede der Felder erklären heroImage und ogImage und die Fragment-Vorschauregeln.
7. Welches Bild erscheint beim Teilen?
Ein Freigabebild gehört zur Linkvorschau und ist nicht das Titelbild der Seite.
Standardmäßig erzeugt der Build ein 1200×630-PNG aus Titel, Autor und Website-Name, ohne Bilddienst oder Browser. Baue und veröffentliche nach Änderungen erneut. theme.footer.showCredits steuert auch die Theme-Nennung auf automatisch erzeugten Freigabebildern, verändert aber keine hochgeladenen eigenen Bilder.
Ein Freigabebild für einen Beitrag setzen
Lege share.png neben den Artikel und setze im frontmatter:
ogImage: ./share.png
Oder verwende public/images/share.png mit ogImage: /images/share.png. Das Feld unterstützt auch direkte HTTPS-Bild-URLs. Relative lokale Bilder verarbeitet das Artikelschema; public-Pfade werden auf Existenz geprüft. Die Verfügbarkeit externer Bilder hängt vom fremden Server ab.
Ein Standardbild für Seiten ohne eigenes Bild festlegen
Vereinige im vorhandenen obersten site von src/site.config.ts:
site: {
ogImage: '/images/site-share.jpg',
},
Lege vorher die Datei unter public/images/site-share.jpg ab. site.ogImage unterstützt auch HTTPS-Bild-URLs. Fehlend oder leer verwendet es das integrierte 1200×630-Standardbild. Artikelrelative Pfade sind hier nicht erlaubt.
Die aktuelle Reihenfolge:
- Ausdrücklich gesetztes
ogImagedes Beitrags. - Automatisches Artikel-Freigabebild, wenn aktiviert.
heroImagenach Deaktivierung vontheme.socialImage.enabled.site.ogImagebei Seiten ohne eigenes Bild, zuletzt das integrierte Standardbild.
Nur site.ogImage zu ändern ersetzt daher keine automatischen Artikelbilder. Fragments und ihre #ID-Links teilen das Website-Standardbild, ohne einzelne Karten pro Fragment.
Automatische Bilder liegen unter dist/_social/. Plattformen lesen die Metadaten der veröffentlichten Seite und können alte Bilder cachen. Eine neue lokale Vorschau bedeutet keine sofortige Aktualisierung dort.
8. Probleme systematisch prüfen
| Symptom | Zuerst prüfen |
|---|---|
| Bild fehlt | Existenz, Großschreibung und relativen Pfad ab aktueller Markdown-Datei; kein public in public-URLs |
| Titelbildvorbereitung scheitert | Ist heroImage eine lokale Projektdatei statt externer oder public-URL? Vollständiger Fehler im Terminal |
| missing/stale/modified derivatives | build oder prepare-covers repariert Varianten automatisch; –check bleibt schreibgeschützt. Bei Fehlern Originale prüfen |
| Bild in public erzeugt keine Größen | Wird es tatsächlich im Fragment referenziert? Normale public-Bilder im Beitragstext gehören nicht zu diesem Scan |
| GIF oder SVG bleibt groß | Mehrbild- und Vektordateien bleiben im Original; der Befehl konvertiert keine Videos und komprimiert keine Animationen |
| Externes Fragment-Bild langsam oder mit Layoutsprung | Keine lokale Konvertierung oder automatische Ermittlung externer Maße; Quelle optimieren und korrekte Maße setzen |
| Lokal vorhanden, veröffentlicht fehlend | Sind Originale committet, der Build erfolgreich, das gesamte dist bereitgestellt und Ressourcenpfade unverändert? |
| Freigabebild veraltet | Neu gebaut und veröffentlicht? Hat ein Artikelbild Vorrang vor dem Website-Standard? Plattform-Cache? |
Bei eigenen Astro srcDir-/publicDir-Einstellungen oder Quellpfaden mit base verwende die dev-Vorbereitung dieses Projekts. Der eigenständige prepare-covers-Befehl verwendet Standardordner. Teilweise base-Unterstützung bei Bildern bedeutet nicht, dass das gesamte Theme beliebige Unterverzeichnis-Deployments unterstützt.
Installation und Updates erklärt Blog installieren und eigene Angaben eintragen, Text und Beitragsfelder Den ersten Beitrag schreiben.
Tutorial-Navigation und Konfiguration
Zurück: Den ersten Beitrag schreiben · Weiter: Ein Fragment veröffentlichen · Alle acht Tutorials.
Passende Felder: Artikel-Titelbilder und Freigabebilder, Fragment-Bildvorschau, Website-Standardbild. Vollständige Pfade, Vorgaben und Grenzen stehen im Konfigurationsverzeichnis.