Guía 3: añadir imágenes a entradas y fragments

$ publicado 2026-11-13 | | actualizado 2026-11-14
Contexto: Añade imágenes, prepara derivados persistentes localmente y publica todos los recursos necesarios.

Originales, portadas, archivos adaptativos e imágenes compartidas


Salida
palabras 1.7k tokens 2.2k

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:

![Descripción de lo que aparece en la foto](./photo.jpg)

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

![Descripción de lo que aparece en la foto](/images/shared-photo.jpg)

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:

![Descripción de la imagen de esta nota](/images/fragments/my-photo.png)

También puedes poner photo.png junto al fragment y usar ![Descripción de la imagen](./photo.png). 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:

  1. Markdown de entradas/fragments y originales nuevos o sustituidos.
  2. 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:

  1. ogImage explícita de la entrada.
  2. Imagen automática de entrada mientras esté activa.
  3. heroImage cuando theme.socialImage.enabled está desactivado.
  4. site.ogImage para 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.

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.