Zum Inhalt springen
⌘K

Bilder

Bereite lokale Bilder in Markdown und MDX auf oder liefere Ardos Bildkompositionen über einen Bildprovider aus.

Als Markdown ansehen
Auf dieser Seite

Setze images auf oberster Ebene in ardo.config.ts, um lokale Markdown-Bilder und die MDX-Komponente Image aufzubereiten. Ohne diese Option behalten bestehende Dokumentationen ihre normalen Bild-URLs. Publikationen bereiten ihre Bilder immer auf.

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "Example project",
  images: { widths: [384, 640, 960, 1280, 1920] },
})

Relative Pfade beziehen sich auf die ursprüngliche Markdown-Datei; Pfade mit / am Anfang auf public. Ergänze Bildausschnitte und abweichende Presets in der Frontmatter-Zuordnung images der Seite, mit dem Bildpfad als Schlüssel. Das gemeinsame Ausschnittmodell und die Presets stehen unter Publikationsbilder.

Auslieferungsprovider

Sharp bleibt der Standard: responsive AVIF-Dateien und ein JPEG-Fallback. Ein Provider ersetzt die Rasterkodierung durch URLs; Ardo verantwortet weiterhin Ausschnitte, Presets, HTML, Feeds und Social-Metadaten. Im Entwicklungsmodus nutzt Ardo lokale Sharp-Dateien, damit unveröffentlichte Originale sichtbar bleiben.

import type { ImageProvider } from "ardo/config"

const provider: ImageProvider = {
  source({ sha256, extension }) {
    return {
      fileName: `images/${sha256}.${extension}`,
      url: `https://images.example.com/${sha256}.${extension}`,
    }
  },
  url({ source, crop, width, height, kind }) {
    // Adapt these parameters to your own image endpoint.
    const url = new URL(source)
    url.searchParams.set("crop", [crop.left, crop.top, crop.width, crop.height].join(","))
    url.searchParams.set("width", String(width))
    url.searchParams.set("height", String(height))
    url.searchParams.set("format", kind === "fallback" ? "jpeg" : "webp")
    return { url: url.href, type: kind === "fallback" ? "image/jpeg" : "image/webp" }
  },
}

// In defineArdoConfig:
// images: { provider }

Beide Hooks müssen synchron und deterministisch arbeiten und dürfen weder Netzwerkanfragen noch Uploads ausführen. Ardo gibt jedes Original einmal je Ausgabepfad bytegetreu aus. Der Source-Hook erhält den vollständigen SHA-256-Hash, die kanonische Dateiendung, die ausgerichteten Abmessungen, die ursprüngliche EXIF-Ausrichtung und die Deployment-Basis. Verwende den vollständigen Hash im Dateinamen; dein Deployment lädt die ausgegebenen Originale hoch.

Der Endpunkt muss die EXIF-Ausrichtung vor dem exakten Ausschnitt in ganzzahligen Pixelkoordinaten anwenden und danach auf die angeforderten Abmessungen skalieren. Ardo erkennt keine Gesichter. Der zurückgegebene MIME-Typ muss der Antwort entsprechen und innerhalb einer Ausschnittfamilie gleich bleiben. Varianten erlauben AVIF, WebP, JPEG oder PNG; Fallbacks benötigen JPEG oder PNG für Feeds und Social-Bilder. URLs müssen normalisierte absolute HTTP(S)-URLs ohne eingebettete Zugangsdaten sein oder root-relative Pfade, die die Deployment-Basis bereits enthalten. Sie dürfen nicht auf ein Komma enden, weil das srcset bricht.

Dateinamen der Originale müssen relative Bildpfade ohne Punktsegmente sein. Kollisionen mit anderen Bildern, gebündelten Assets oder öffentlichen Dateien lassen den Build fehlschlagen. SVG und animierte Bilder werden unverändert ohne Rastervarianten ausgegeben; Bildausschnitte bleiben dafür ausgeschlossen. Externe HTTP-Bilder bleiben unverändert und werden nie heruntergeladen.

Originale werden mit ihren EXIF- und XMP-Metadaten veröffentlicht, einschließlich eines Standorts. Der Build warnt bei jedem Original mit GPS-Daten. Entferne die Metadaten vor dem Commit, wenn der Standort eines Bildes privat bleiben soll.

Kompatibilität mit Publikationen

images auf oberster Ebene gilt für Titelbilder, Inhaltsbilder, Autorenporträts und dafür aktivierte Dokumentation. Porträts behalten die Breiten 96 und 192 Pixel. Das bestehende publication.images bleibt als kompatibler Alias für Publikationseinstellungen erhalten. Werte auf oberster Ebene haben feldweise Vorrang; benannte Presets werden zusammengeführt, wobei ein explizites Preset auf oberster Ebene gewinnt.

Diese Seite auf GitHub bearbeitenZuletzt aktualisiert: 13. November 2026