Bilder
Erfahren Sie, wie Jamdesk Bildgrößen, Bildunterschriften, Hell-/Dunkelvarianten und unterstützte Formate für klare, zugängliche Dokumentation verarbeitet.
Jamdesk rendert Bilder mit abgerundeten Ecken und einheitlichen Abständen. Legen Sie Dateien in Ihrem /images-Verzeichnis ab und verweisen Sie mit Standard-Markdown darauf.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Standard-Markdown
Verwenden Sie die vertraute Syntax :
Pfade beginnen im Stammverzeichnis Ihres Projekts. Ein Bild unter your-docs/images/screenshot.webp wird als /images/screenshot.webp referenziert.
Bildabmessungen
Fügen Sie nach der Bild-URL (durch ein Leerzeichen getrennt) =WIDTHxHEIGHT an, um die Größe zu steuern:
Legen Sie nur eine Abmessung fest, wird die andere proportional skaliert:
Das ist hilfreich, wenn Sie eine einheitliche Spalte mit Screenshots derselben Breite benötigen oder ein hochauflösendes Bild auf eine angemessene Anzeigegröße verkleinern möchten.
Bildunterschriften
Binden Sie ein Bild in die <Frame>-Komponente ein, um einen Rahmen und eine Bildunterschrift darunter hinzuzufügen:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame zeichnet einen dezenten Rahmen um das Bild und platziert den Bildunterschriftstext darunter. Die Komponente funktioniert mit beliebigen Inhalten, nicht nur mit Bildern.
Hell-/Dunkelmodus
Dokumentationswebsites benötigen häufig unterschiedliche Bildvarianten für jedes Farbschema: Ein Logo auf weißem Hintergrund sieht im Dunkelmodus falsch aus.
Das Attribut srcDark
Der einfachste Ansatz. Jamdesk tauscht die Bildquelle basierend auf dem aktiven Theme aus:
<img
src="/_jd/images/logo-light.webp?v=msp3nl3i"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Der Browser lädt nur das Bild, das dem aktuellen Farbschema entspricht.
Das HTML-Element <picture>
Wenn Sie standardmäßiges HTML benötigen, das auch außerhalb von Jamdesk funktioniert, verwenden Sie <picture> mit einer Media Query:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=msp3nl3i" alt="Company logo" />
</picture>Der <picture>-Ansatz berücksichtigt die Farbschemaeinstellung des Betriebssystems. Das Attribut srcDark reagiert stattdessen auf den Theme-Umschalter von Jamdesk, was für Dokumentationsseiten normalerweise die gewünschte Option ist.
Unterstützte Formate
| Format | Am besten geeignet für | Hinweise |
|---|---|---|
| PNG | Screenshots, UI-Aufnahmen | Verlustfreie Qualität, unterstützt Transparenz. Größere Dateien. |
| JPEG | Fotografien | Gute Komprimierung, keine Unterstützung für Transparenz. |
| SVG | Symbole, Diagramme, Logos | Vektorformat, das ohne Qualitätsverlust auf jede Größe skaliert werden kann. Sehr kleine Dateigröße. |
| GIF | Einfache Animationen | Kann schnell sehr groß werden. Für alles über wenige Frames sollten Sie kurze .mp4-Schleifen in Betracht ziehen. |
| WebP | Allgemeine Verwendung | Bei vergleichbarer Qualität kleiner als PNG und JPEG. Funktioniert in allen modernen Browsern. |
WebP bietet für die meisten Dokumentationsbilder das beste Verhältnis von Dateigröße und Qualität. Wenn Sie Transparenz benötigen, unterstützt WebP auch diese, sodass Sie kein PNG benötigen.
Bewährte Vorgehensweisen
Alternativtext erfüllt zwei Zwecke: Screenreader verwenden ihn für die Barrierefreiheit, und er wird als Platzhalter angezeigt, wenn das Bild nicht geladen werden kann. Beschreiben Sie, was das Bild tatsächlich zeigt.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Verwenden Sie für dekorative Bilder, die keine Informationen hinzufügen (Hintergrundmuster, Trennlinien), einen leeren Alternativtext: .
Große Bilder verlangsamen das Laden von Seiten, insbesondere bei mobilen Verbindungen. Zielgrößen:
- Screenshots/UI: PNG oder WebP, unter 500 KB
- Fotos: JPEG oder WebP, unter 200 KB
- Symbole und Diagramme: möglichst SVG
Squoosh und TinyPNG komprimieren Bilder ohne sichtbaren Qualitätsverlust. Lassen Sie Screenshots vor dem Commit durch eines dieser Tools laufen.
Oder lassen Sie Jamdesk die Verarbeitung beim Build übernehmen. Aktivieren Sie die automatische WebP-Konvertierung in Ihrer docs.json, damit alle von Ihnen committeten PNG- oder JPG-Dateien bei jedem Build optimiert werden.
Screenshots, die zwischen verschiedenen Breiten wechseln, wirken unübersichtlich. Wählen Sie eine Standardbreite für Aufnahmen (1200px funktioniert gut) und verwenden Sie sie in Ihrer gesamten Dokumentation. Jamdesk skaliert Bilder automatisch so, dass sie in den Inhaltsbereich passen. Einheitliche Quelldimensionen sorgen daher für einheitliche gerenderte Ergebnisse.
Jamdesk generiert automatisch eine gebrandete Social Card mit 1200×630 für jede Seite. Sie können sie pro Seite mit og:image im Frontmatter überschreiben. Rufen Sie nach einem Build die Seiten-URL mit dem kostenlosen Tool OpenGraph Preview auf, um zu sehen, wie die Card auf X, Facebook, LinkedIn, Slack, Discord und weiteren Plattformen gerendert wird. Eine vollständige Einrichtung finden Sie unter SEO-Optimierung.
Dateiorganisation
Gruppieren Sie Bilder in Unterverzeichnissen, die Ihre Inhaltsstruktur widerspiegeln. So bleiben sie auffindbar, wenn Ihre Dokumentation wächst:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonVerweisen Sie mit dem vollständigen Pfad aus dem Stammverzeichnis Ihres Projekts darauf:
Vermeiden Sie Leerzeichen in Dateinamen von Bildern. Verwenden Sie stattdessen Bindestriche: api-response.webp, nicht api response.webp.