Guía 3: añadir imágenes a entradas y fragments
Originales, portadas, archivos adaptativos e imágenes compartidas
En esta página
Esta es la parte 3 de 8. Consulta el orden completo · Busca campos de configuración.
No necesitas producir varios tamaños manualmente ni sustituir las referencias por nombres generados. Añade el original, úsalo en una entrada o fragment y deja que el servidor de desarrollo local prepare los archivos adaptativos.
Este tutorial supone los directorios predeterminados src/ y public/ del starter. Distingue primero el propósito de la imagen:
| Propósito | Dónde configurarlo | Tratamiento actual |
|---|---|---|
| Cuerpo de entrada | Imagen Markdown o MDX | Flujo Markdown/MDX existente; fuera de la preparación persistente de portadas descrita abajo. |
| Portada de entrada | heroImage del frontmatter |
Archivos adaptativos preparados localmente, compartidos por listas y detalle. |
| Imagen de fragment | Imagen Markdown, de referencia o HTML img del cuerpo |
Las imágenes locales admitidas usan los mismos derivados persistentes en listas y vistas previas de inicio. |
| Vista previa al compartir | ogImage individual o site.ogImage |
Lógica independiente para compartir, no una miniatura de portada. |
1. Añadir el original al proyecto
Una imagen usada por una sola entrada puede estar a su lado:
src/content/blog/zh/
my-first-post.md
photo.jpg
cover.jpg
También puedes poner imágenes junto al Markdown de un fragment. Las compartidas pueden ir en public/images/:
public/images/
shared-photo.jpg
fragments/
my-photo.png
Crea los directorios si faltan. Prefiere letras simples, números y guiones; evita confundir mayúsculas. Las URLs usan /, no rutas locales C:\..., D:\... ni barras invertidas. En un alojamiento sensible a mayúsculas, Photo.jpg y photo.jpg pueden ser archivos distintos.
Conserva el original. Los WebP generados son derivados de visualización, no copias de seguridad sustitutivas.
2. Insertar una imagen en el cuerpo de una entrada
En el Markdown, inserta:

./photo.jpg es relativo al archivo de entrada; en el ejemplo de directorios corresponde al archivo vecino. Para un archivo público, usa:

Corresponde a public/images/shared-photo.jpg, sin public en la URL. El texto entre corchetes es alternativo: describe la imagen en vez de poner solo «imagen».
Las imágenes normales del cuerpo admiten pulsación o foco y Enter/Espacio para abrir una vista ampliada. Cierra con Esc, botón o fondo. Se excluyen portadas e imágenes dentro de enlaces/botones. La vista usa la fuente seleccionada por el navegador; no descarga un original mayor ni es una galería.
Ejecutar prepare-covers no comprime todas las imágenes del cuerpo. Procesa bancos de portadas, referencias de portada e imágenes locales de fragments. Una imagen pública de un cuerpo normal puede seguir descargando el original. Elige dimensiones adecuadas y evita capturas de varios megabytes.
3. Establecer una portada
Pon cover.jpg junto a la entrada y añade o edita su frontmatter:
heroImage: ./cover.jpg
heroImage es opcional. Si existe, debe referenciar una imagen local del proyecto, no una URL HTTPS directa. No trates /images/cover.jpg como URL pública para este campo: sus reglas difieren de las imágenes del cuerpo.
Para gestionar portadas centralmente, usa src/assets/blog/covers/originals/. Si la entrada está en src/content/blog/zh/my-first-post.md y el original en src/assets/blog/covers/originals/my-cover.jpg, escribe:
heroImage: ../../../assets/blog/covers/originals/my-cover.jpg
La portada no se inserta sola en el cuerpo. Aparece en listas de entradas/etiquetas y la zona de portada del detalle. El diseño puede recortar la zona visible, pero los derivados conservan la proporción original y no eligen automáticamente una persona o sujeto como foco.
La selección aleatoria de new-post solo lee src/assets/blog/default-covers/. Añadir una imagen a covers/originals/ no la incluye en esa selección; referencia explícitamente los originales nuevos.
4. Añadir imágenes a fragments
Con theme.fragments.enabled: false, dev, build y prepare-covers/doctor omiten referencias de imágenes del contenido de Fragments. No exigen originales ni derivados de imágenes incluidas únicamente por esas referencias. Las referencias de portada y los conjuntos src/assets/blog/default-covers/ y src/assets/blog/covers/originals/ siguen preparándose y validándose, aunque una imagen se use solo en Fragments. No se borran archivos; reactivar restablece el procesamiento de Fragments.
Nota de versión: El aislamiento de imágenes al desactivar requiere 0.36.1 o posterior; no está en 0.36.0. No lo supongas disponible en versiones anteriores.
Pon el original en public/images/fragments/my-photo.png y escribe esto en el cuerpo de un fragment existente:

También puedes poner photo.png junto al fragment y usar . Añadir un archivo a public no inicia un escaneo universal de imágenes: debe estar referenciado por un fragment real.
Se admiten imágenes de referencia:
![Descripción de la imagen][photo]
[photo]: /images/fragments/my-photo.png
Usa HTML para dimensiones manuales:
<img src="/images/fragments/my-photo.png" alt="Descripción de la imagen" width="640" height="360" />
Estas dimensiones son ejemplos; utiliza la proporción real. Las imágenes locales admitidas reciben width/height ausentes. Se conservan las dimensiones existentes; si solo hay una, se calcula la otra con la proporción de origen. No se corrigen dimensiones existentes incorrectas.
La primera imagen de cada página de lista carga con prioridad; las restantes y las miniaturas de inicio usan carga diferida. Las vistas previas de inicio tienen altura máxima y recortan el exceso. No son visores completos: pulsa la tarjeta para abrir el fragment. Consulta publicar fragments para creación, IDs estables y comentarios.
5. Preparar archivos adaptativos localmente
Tras referenciar por primera vez una imagen o sustituir su original, inicia el desarrollo local desde la raíz:
npm run dev
dev prepara archivos ausentes u obsoletos y responde a cambios de originales y referencias pertinentes. build y doctor, también en CI, usan el mismo preparador y reparan selectivamente los derivados necesarios. Para prepararlos sin iniciar páginas ni comprobaciones completas, detén dev y ejecuta:
npx @anglefeint/astro-theme prepare-covers
Para validar los archivos existentes sin generar sustitutos:
npx @anglefeint/astro-theme prepare-covers --check
No hace falta recodificarlo todo. Se comparan hashes de origen, receta y salida para decidir qué reutilizar. Cambiar originales actualiza sus derivados; las salidas individuales ausentes o modificadas se reparan selectivamente. No edites el manifiesto, renombres archivos generados ni pongas sus URLs en las entradas.
Reglas actuales:
- Los raster estáticos se convierten a WebP con calidad 80: objetivo con pérdidas, sin garantía de píxeles idénticos.
- Los anchos candidatos son 400, 640, 800, 960 y 1200px, conservando los adecuados al origen. Se añade su ancho cuando hace falta hasta 1200px, sin ampliar imágenes pequeñas.
- Se corrige orientación EXIF y conserva proporción, sin crear recortes de composición alternativos.
- SVG y animaciones de varios fotogramas mantienen su formato, sin convertirse en WebP estático. Un GIF de un fotograma puede procesarse como estático; la extensión por sí sola no determina el tratamiento.
- El banco predeterminado, el de originales y las referencias reales delimitan el alcance. No se convierte toda imagen pública.
El navegador elige candidatos con srcset, sizes, tamaño visible y densidad de píxeles. No necesitas directorios separados por tamaño. El máximo es 1200px, sin garantizar detalle equivalente al original en pantallas grandes de alta densidad.
6. Qué guardar en Git y qué ocurre al desplegar
Los archivos preparados se organizan así:
src/assets/blog/covers/
originals/ # si usas este directorio de originales
manifest.json # orígenes, dimensiones, reglas y hashes de salida
generated/ # archivos adaptativos persistentes
Guarda conjuntamente:
- Markdown de entradas/fragments y originales nuevos o sustituidos.
- Todo
src/assets/blog/covers/, incluidos manifiesto y generados.
Guarda también los originales de public o junto a entradas, no solo originals/. Los derivados de fragments también están aquí pese al nombre blog/covers.
Detén dev antes de publicar y ejecuta npm run doctor local. Después usa npm run preview para revisar la compilación. doctor ya compila: no repitas inmediatamente. El alojamiento sigue usando npm run build, salida dist y todos sus archivos.
Build y doctor preparan los derivados necesarios, también en CI. Reutilizan los válidos y regeneran los ausentes, obsoletos o dañados; no necesitan que el alojamiento conserve cachés. Un original inexistente, una ruta que escape del proyecto o una imagen ilegible siguen causando un error. Guarda originales y, para reutilizar los resultados, también manifiesto y derivados.
Nota de versión: La preparación automática de imágenes durante build y doctor en CI requiere 0.36.2 o posterior. Con 0.36.1, ejecuta primero dev o prepare-covers para preparar los derivados. prepare-covers --check y la sincronización de configuración siguen siendo comprobaciones de solo lectura.
Los derivados usados se copian a _blog-covers/ en la salida. No subas solo HTML ni omitas ese directorio. Los generados antiguos sin uso no se borran automáticamente; revisa referencias antes de limpiar y no elimines originales necesarios.
Consulta heroImage/ogImage y reglas de vista previa de fragments para distinguir campos.
7. Qué imagen aparece al compartir un enlace
Es la vista previa de la tarjeta de enlace, distinta de la portada visible.
Por defecto, cada entrada genera durante la compilación un PNG 1200×630 con título, autor y nombre del sitio. No necesita servicio de imágenes ni navegador. Recompila y despliega si cambias esos valores. theme.footer.showCredits también controla el crédito del tema en estas imágenes automáticas, sin modificar imágenes personalizadas subidas.
Elegir la imagen para compartir de una entrada
Pon share.png junto a la entrada y añade:
ogImage: ./share.png
O usa public/images/share.png con ogImage: /images/share.png. También admite URLs HTTPS. El schema de imágenes procesa archivos relativos; se comprueba la existencia de rutas públicas. La disponibilidad remota depende del otro servidor.
Definir el respaldo para páginas sin imagen propia
Combina dentro del site superior existente en src/site.config.ts:
site: {
ogImage: '/images/site-share.jpg',
},
Añade primero public/images/site-share.jpg. site.ogImage también admite HTTPS. Si falta o está en blanco, usa la imagen integrada 1200×630 del tema. Aquí no valen rutas relativas a una entrada.
Prioridad actual:
ogImageexplícita de la entrada.- Imagen automática de entrada mientras esté activa.
heroImagecuandotheme.socialImage.enabledestá desactivado.site.ogImagepara páginas sin imagen específica; después, el respaldo integrado.
Cambiar solo site.ogImage no sustituye las automáticas de entrada. Las páginas de fragments y sus enlaces #ID comparten el respaldo global, sin tarjeta individual generada por fragment.
Las automáticas están en dist/_social/. Las plataformas leen metadatos publicados y pueden mantener cachés antiguas; ver la imagen nueva localmente no actualiza sus vistas inmediatamente.
8. Resolver problemas de imágenes
| Síntoma | Qué comprobar primero |
|---|---|
| Falta una imagen | Existencia, mayúsculas exactas y rutas relativas al Markdown; omite public en URLs públicas. |
| Falla la preparación de portada | heroImage debe ser un archivo local, no URL remota/pública; lee el error completo. |
| Derivados missing/stale/modified | Detén dev, ejecuta prepare-covers local, guarda originales, manifiesto y generados, y recompila. |
| Archivo público sin tamaños generados | ¿Está referenciado por un fragment? Las imágenes públicas de cuerpos normales quedan fuera. |
| GIF/SVG sigue pesando mucho | Animaciones/vector pasan sin conversión; no se convierten a vídeo ni se comprimen con este comando. |
| Imagen remota de fragment lenta o desplaza el diseño | No se convierte ni mide localmente. Optimiza el origen y añade dimensiones correctas. |
| Funciona localmente pero no publicado | Comprueba que originales y generados estén en Git, todo dist publicado y rutas sin reescrituras indebidas. |
| La vista al compartir sigue antigua | Revisa compilación/despliegue, prioridad de imagen individual y cachés de plataformas. |
Si personalizas srcDir, publicDir o fuentes con base de Astro, prepara a través de dev de ese proyecto. prepare-covers independiente usa los directorios predeterminados. La compatibilidad parcial de imágenes con base no implica que todo el tema admita cualquier despliegue en subdirectorios.
Para instalar/actualizar, consulta instalar el blog y poner tus datos. Consulta escribir tu primera entrada para campos y sintaxis.
Navegación de tutoriales y diccionario de configuración
Anterior: escribir tu primera entrada · Siguiente: publicar un fragment · Los ocho tutoriales.
Campos relacionados: portadas e imágenes compartidas, vistas previas de fragments, respaldo global. El índice contiene rutas, valores y límites.