Aller au contenu
⌘K

Images

Prépare les images locales en Markdown et MDX ou diffuse les compositions d’Ardo via un fournisseur d’images.

Voir en Markdown
Sur cette page

Définis images au premier niveau dans ardo.config.ts pour traiter les images Markdown locales et le composant MDX Image. Sans cette option, la documentation existante conserve ses URL d’images habituelles. Les publications traitent toujours leurs images.

import { defineArdoConfig } from "ardo/config"

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

Les chemins relatifs partent du fichier Markdown original ; ceux commençant par / se trouvent dans public. Ajoute les cadrages et presets spécifiques dans la table images du frontmatter, avec le chemin de l’image comme clé. Consulte les images de publication pour le modèle de cadrage et les presets communs.

Fournisseurs de diffusion

Sharp reste le choix par défaut : des fichiers AVIF responsifs et un JPEG de repli. Un fournisseur remplace l’encodage raster par des URL ; Ardo conserve les cadrages, presets, le HTML, les flux et les métadonnées sociales. En développement, les fichiers Sharp locaux permettent de voir les originaux non publiés.

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 }

Les deux hooks doivent être synchrones, déterministes et sans requête réseau ni téléversement. Ardo émet chaque original une fois par chemin de sortie, sans modifier ses octets. Le hook source reçoit le SHA-256 complet, l’extension canonique, les dimensions après orientation, l’orientation EXIF initiale et la base de déploiement. Utilise le hash complet dans le nom du fichier ; ton déploiement téléverse les originaux émis.

Le point de terminaison doit appliquer l’orientation EXIF avant le recadrage exact en pixels entiers, puis redimensionner selon les dimensions demandées. Ardo ne détecte pas les visages. Le type MIME retourné doit correspondre à la réponse et rester identique dans une famille de cadrage. Les variantes acceptent AVIF, WebP, JPEG ou PNG ; les replis exigent JPEG ou PNG pour les flux et images sociales. Les URL doivent être absolues en HTTP(S), normalisées et sans identifiants intégrés, ou être des chemins relatifs à la racine incluant déjà la base de déploiement. Elles ne doivent pas se terminer par une virgule, car cela casserait srcset.

Les noms des originaux doivent être des chemins d’image relatifs sans segments point. Une collision avec une autre image, une ressource du bundle ou un fichier public fait échouer le build. Les SVG et images animées sont émis sans modification ni variante raster ; le cadrage reste indisponible. Les images HTTP externes restent inchangées et ne sont jamais téléchargées.

Les originaux sont publiés avec leurs métadonnées EXIF et XMP, y compris toute localisation. Le build avertit pour chaque original contenant des données GPS. Supprime les métadonnées avant de valider les images dont la localisation doit rester privée.

Compatibilité des publications

images au premier niveau s’applique aux couvertures, images du contenu, portraits et documents activés. Les portraits conservent leurs largeurs de 96 et 192 pixels. publication.images reste un alias compatible pour les publications. Les valeurs du premier niveau priment champ par champ ; les presets nommés fusionnent et un preset explicite du premier niveau l’emporte.

Modifier cette page sur GitHubDernière mise à jour: 13 novembre 2026