Bilder
Bilder skalieren, Bildunterschriften hinzufügen, Hell- und Dunkelvarianten wechseln und ein unterstütztes Format für scharfe, barrierefreie Doku-Visuals wählen.
Jamdesk rendert Bilder mit abgerundeten Ecken und einheitlichen Abständen. Lege Dateien in dein /images-Verzeichnis und referenziere sie mit Standard-Markdown.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Standard-Markdown
Verwende die Syntax :
Pfade beginnen im Stammverzeichnis deines Projekts. Ein Bild unter your-docs/images/screenshot.webp wird als /images/screenshot.webp referenziert.
Bildabmessungen
Hänge =BREITExHÖHE nach der Bild-URL an (durch ein Leerzeichen getrennt), um die Größe zu steuern:
Wenn nur eine Abmessung gesetzt wird, skaliert die andere proportional:
Damit hältst du eine Reihe von Screenshots auf einheitlicher Breite oder verkleinerst ein hochauflösendes Bild für die Anzeige.
Bildunterschriften
Umschließe ein Bild mit der <Frame>-Komponente, um einen Rahmen und eine Bildunterschrift darunter hinzuzufügen:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame funktioniert mit jedem Inhalt darin, nicht nur mit Bildern.
Zum Vergrößern klicken
Klicke auf ein Bild, um es auf Bildschirmen ab 768px Breite im Vollbild zu öffnen. Schließe das vergrößerte Bild mit Escape oder einem Klick irgendwo.
Füge noZoom zu einem <img loading="lazy">-Tag hinzu, damit es nicht vergrößert wird:
<img src="/_jd/images/diagram.png?v=mw83zxfs" alt="Architecture diagram" data-no-zoom="true" />Markdown-Bilder () haben keine Attributsyntax. Sie können die Vergrößerung nicht deaktivieren. Verwende ein <img loading="lazy">-Tag, wenn du noZoom brauchst.
Hell-/Dunkelmodus
Doku-Seiten brauchen oft unterschiedliche Bildvarianten für jedes Farbschema: Ein Logo auf weißem Hintergrund wirkt im Dunkelmodus falsch.
Das Attribut srcDark
Jamdesk tauscht die Bildquelle passend zum aktiven Design:
<img
src="/_jd/images/logo-light.webp?v=mw83zxfs"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Der Browser lädt nur das Bild, das zum aktuellen Farbschema passt.
Das HTML-Element <picture>
Verwende <picture> mit einer Media-Query für Standard-HTML, das auch außerhalb von Jamdesk funktioniert:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mw83zxfs" alt="Company logo" />
</picture>Der <picture>-Ansatz berücksichtigt die Farbschema-Einstellung des Betriebssystems. Das Attribut srcDark folgt stattdessen dem Design-Umschalter von Jamdesk. Für Dokumentation ist das meist das Gewünschte.
Unterstützte Formate
| Format | Am besten für | Hinweise |
|---|---|---|
| PNG | Screenshots, UI-Aufnahmen | Verlustfreie Qualität, unterstützt Transparenz. Größere Dateien. |
| JPEG | Fotos | Gute Kompression, keine Transparenz. |
| SVG | Icons, Diagramme, Logos | Vektorformat, skaliert auf jede Größe ohne Qualitätsverlust. Sehr kleine Dateigröße. |
| GIF | Einfache Animationen | Kann schnell groß werden. Ziehe kurze .mp4-Schleifen für mehr als ein paar Frames vor. |
| WebP | Allgemeiner Einsatz | Kleiner als PNG und JPEG bei vergleichbarer Qualität. Funktioniert in allen modernen Browsern. |
WebP bietet für die meisten Doku-Bilder das beste Verhältnis von Größe zu Qualität. Es unterstützt auch Transparenz. Dafür brauchst du kein PNG.
Bewährte Vorgehensweisen
Screenreader lesen Alt-Text vor. Er wird außerdem als Platzhalter angezeigt, wenn das Bild nicht lädt. Beschreibe, was das Bild zeigt.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Für dekorative Bilder ohne Informationsgehalt (Hintergrundmuster, Trenner) verwende leeren Alt-Text: .
Schwere Bilder verlangsamen das Laden von Seiten, besonders bei mobilen Verbindungen. Zielgrößen:
- Screenshots/UI: PNG oder WebP, unter 500KB
- Fotos: JPEG oder WebP, unter 200KB
- Icons und Diagramme: wenn möglich SVG
Squoosh und TinyPNG komprimieren Bilder ohne sichtbaren Qualitätsverlust. Lass Screenshots vor dem Commit durch eines dieser Tools laufen.
Jamdesk kann auch zur Build-Zeit komprimieren. Aktiviere die automatische WebP-Konvertierung in deiner docs.json. Dann optimiert Jamdesk bei jedem Build jedes PNG oder JPG, das du committest.
Screenshots mit wechselnden Breiten wirken unordentlich. Wähle eine Standard-Aufnahmebreite (1200px funktioniert gut) und verwende sie in deiner gesamten Doku. Jamdesk skaliert Bilder auf den Inhaltsbereich. Einheitliche Ausgangsabmessungen ergeben einheitliche Darstellungen.
Jamdesk erzeugt für jede Seite eine gebrandete Social Card mit 1200×630. Überschreibe sie pro Seite mit og:image im Frontmatter. Nach einem Build kannst du die Seiten-URL mit dem kostenlosen Tool OpenGraph Preview prüfen, um zu sehen, wie die Karte auf X, Facebook, LinkedIn, Slack, Discord und weiteren Plattformen aussieht. Die vollständige Einrichtung findest du unter SEO-Optimierung.
Dateiorganisation
Gruppiere Bilder in Unterverzeichnisse, die deine Inhaltsstruktur widerspiegeln:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonReferenziere sie mit dem vollständigen Pfad ab deinem Projektstammverzeichnis:
Vermeide Leerzeichen in Bilddateinamen. Verwende stattdessen Bindestriche: api-response.webp, nicht api response.webp.