Imágenes
Prepara imágenes locales en Markdown y MDX o entrega las composiciones de Ardo mediante un proveedor de imágenes.
En esta página
Define images en el nivel superior de ardo.config.ts para procesar imágenes Markdown locales y el componente MDX Image. Sin esta opción, la documentación existente conserva sus URL habituales. Las publicaciones siempre procesan sus imágenes.
import { defineArdoConfig } from "ardo/config"
export default defineArdoConfig({
title: "Example project",
images: { widths: [384, 640, 960, 1280, 1920] },
})
Las rutas relativas parten del archivo Markdown original; las que empiezan por / se resuelven dentro de public. Añade encuadres y ajustes de presets en el mapa images del frontmatter, usando la ruta de la imagen como clave. Consulta imágenes de publicaciones para el modelo de encuadre y los presets compartidos.
Proveedores de entrega
Sharp sigue siendo la opción predeterminada: archivos AVIF adaptables y un JPEG de respaldo. Un proveedor sustituye la codificación ráster por URL; Ardo conserva los recortes, presets, HTML, feeds y metadatos sociales. En desarrollo se usa la salida local de Sharp para mostrar los originales aún no publicados.
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 }
Ambos hooks deben ser síncronos, deterministas y no realizar solicitudes de red ni cargas. Ardo emite cada original una vez por ruta de salida, conservando sus bytes. El hook source recibe el SHA-256 completo, la extensión canónica, las dimensiones orientadas, la orientación EXIF original y la base de despliegue. Usa el hash completo en el nombre; tu despliegue sube los originales emitidos.
El endpoint debe aplicar la orientación EXIF antes del recorte exacto en píxeles enteros y después redimensionar a las dimensiones solicitadas. Ardo no detecta caras. El tipo MIME devuelto debe coincidir con la respuesta y mantenerse en cada familia de recortes. Las variantes admiten AVIF, WebP, JPEG o PNG; los respaldos requieren JPEG o PNG para feeds e imágenes sociales. Las URL deben ser HTTP(S) absolutas normalizadas sin credenciales integradas, o rutas relativas a la raíz que ya incluyan la base de despliegue. No deben terminar en coma, porque eso rompería srcset.
Los nombres de los originales deben ser rutas de imagen relativas sin segmentos de punto. Las colisiones con otras imágenes, recursos empaquetados o archivos públicos hacen fallar el build. Los SVG y las imágenes animadas se emiten sin cambios ni variantes ráster; no admiten encuadre. Las imágenes HTTP externas no cambian y nunca se descargan.
Los originales se publican con sus metadatos EXIF y XMP, incluida cualquier ubicación. La compilación avisa de cada original que contiene datos GPS. Elimina los metadatos antes de confirmar las imágenes cuya ubicación deba seguir siendo privada.
Compatibilidad con publicaciones
images en el nivel superior se aplica a portadas, imágenes del contenido, retratos y documentación activada. Los retratos conservan sus anchuras de 96 y 192 píxeles. publication.images sigue siendo un alias compatible para publicaciones. Los valores superiores prevalecen por campo; los presets con nombre se combinan y un preset superior explícito tiene prioridad.