Añadir imágenes e insignias a un README de GitHub: cuatro formas

Elige la ubicación de la imagen según su propiedad y vida útil

Una imagen de un README es una dependencia de la documentación. Antes de elegir una URL, decide quién es responsable del archivo, si debe cambiar junto con el código, cuánto tiempo debe permanecer disponible y dónde se renderizará el README. Un diagrama de arquitectura con control de versiones tiene requisitos diferentes de una captura de pantalla temporal de una pull request o de una insignia generada a partir de datos activos del proyecto.

Por ejemplo, conserva las capturas de pantalla de instalación junto al README cuando cada versión documente una interfaz diferente. En cambio, un logotipo de la comunidad compartido entre muchos repositorios puede corresponder a un almacenamiento público gestionado de forma centralizada. Evita elegir una ubicación solo porque resulte práctica durante la edición. Mover las imágenes más adelante puede romper etiquetas antiguas, páginas de paquetes, bifurcaciones y enlaces a documentación histórica.

Conserva en el repositorio los recursos específicos de cada versión

Para un recurso registrado, coloca el archivo en un directorio predecible, como docs/images/, y haz referencia a él con Markdown, por ejemplo: ![Settings screen](docs/images/settings.png). Las rutas relativas permiten que el README y la imagen se desplacen juntos entre ramas y bifurcaciones. Resuelve la ruta desde la ubicación del archivo Markdown, no desde la raíz del repositorio, porque un README ubicado dentro de un subdirectorio tiene una ruta base diferente.

Trata la escritura de las rutas como código. Las diferencias entre mayúsculas y minúsculas pueden funcionar en el sistema de archivos de un solo desarrollador, pero fallar en otros entornos. Cambiar el nombre de un directorio, comprimir una imagen o eliminar un archivo que parece no usarse también puede dañar documentos anteriores. Revisa los cambios en las imágenes junto con el texto que depende de ellas y usa nombres de archivo descriptivos en lugar de nombres opacos copiados de una herramienta de capturas de pantalla.

Fija las imágenes de la documentación a una revisión estable cuando la página describa una interfaz o un comportamiento publicados. Una ruta relativa a una rama resulta práctica durante la edición, pero el mismo README puede mostrar imágenes diferentes después de que cambie la rama. Las notas de la versión, los avisos de seguridad y las instrucciones de configuración con versiones se benefician de referencias inmutables, porque así los lectores pueden ver la imagen correspondiente a esa versión exacta en lugar de su reemplazo más reciente.

Trata los archivos adjuntos y las imágenes remotas como dependencias externas

Arrastrar una imagen a un editor de GitHub puede generar una URL de archivo adjunto alojado. Es un método rápido y evita agregar datos binarios al repositorio, pero el recurso resultante no está representado por un archivo normal en el historial de Git. Documenta por qué existe la URL, conserva el original en un lugar controlado y verifica que las transferencias del repositorio o las migraciones de la documentación no dejen al equipo sin una fuente gestionable.

Una URL remota puede reducir el tamaño del repositorio y permitir que un mismo recurso se actualice en varios documentos. También puede fallar por una URL firmada que caducó, un cambio en la política de acceso, un objeto eliminado, un problema de DNS o una restricción contra enlaces directos. Usa una ubicación HTTPS destinada al acceso público persistente, confirma que se permita la redistribución y evita insertar endpoints privados. En github.com, las imágenes Markdown renderizadas se obtienen mediante Camo, el proxy de anonimización de GitHub, que oculta al host los datos de red y del navegador del lector, no puede obtener imágenes que requieren autenticación o una red privada y puede seguir entregando una copia en caché después de que cambie la fuente. Los renderizadores que no usan un proxy para las imágenes aún pueden revelar información del lector al host, por lo que los proyectos que manejan información sensible deben reducir al mínimo los recursos innecesarios de terceros.

Usa Markdown para el significado y HTML solo cuando necesites controlar la disposición

Markdown estándar es la opción predeterminada y portable: ![alternative text](path-or-url). Expresa el propósito de la imagen y funciona en más navegadores de repositorios, registros de paquetes, generadores de documentación y herramientas locales de vista previa. Mantén como secundarios los títulos opcionales que aparecen al pasar el cursor, ya que quienes usan teclado o dispositivos táctiles podrían no acceder nunca a ellos y un título no sustituye el texto alternativo ni una explicación visible.

Un elemento HTML img puede establecer dimensiones cuando, de otro modo, una captura de pantalla dominaría la página. GitHub sanea el HTML, los atributos y los estilos no compatibles, por lo que un posicionamiento complejo puede desaparecer o comportarse de manera diferente a una vista previa local. Prefiere un elemento sencillo con src, alt, width y height. Las URL de datos Base64 hacen que el Markdown sea voluminoso, difícil de revisar y poco portable; además, impiden el almacenamiento normal de archivos en caché y no deben ser la solución habitual para gestionar recursos.

![Diagram showing the request flow from the browser through the API to object storage](docs/request-flow.png)

<p align="center">
  <img
    src="docs/dashboard.png"
    alt="Dashboard showing three completed uploads"
    width="720"
  />
</p>

Prepara las imágenes para el tamaño en que se leerán

No incluyas en un commit una captura de escritorio a resolución completa cuando el README la muestra en una columna de contenido estrecha. Redimensiónala cerca del ancho útil de lectura, pero conserva suficiente densidad de píxeles para que el texto se vea nítido en pantallas de alta densidad. La compresión debe eliminar datos innecesarios sin convertir las etiquetas de la interfaz en artefactos. Compara el resultado optimizado en su tamaño renderizado en lugar de evaluar solo la cifra del tamaño del archivo.

Elige el formato según el contenido. JPEG es adecuado para imágenes fotográficas que no necesitan transparencia. PNG sigue siendo útil para capturas nítidas de interfaces, diagramas con pocos colores y transparencia, aunque puede alcanzar un tamaño considerable. WebP puede funcionar para imágenes mixtas si se prueban todos los renderizadores previstos. SVG es eficaz para diagramas y logotipos creados como vectores, pero solo deben publicarse archivos SVG confiables. Conserva una fuente editable de los diagramas, incluso si el README usa una versión rasterizada exportada.

Escribe el texto alternativo según la función de la imagen

El texto alternativo debe comunicar lo que el lector necesita obtener de la imagen en este contexto. En una captura de pantalla de una prueba exitosa, describe el estado de éxito relevante en lugar de enumerar todos los controles visibles. En un diagrama, resume la relación que ilustra y explica los detalles complejos en el texto cercano. No repitas palabra por palabra un pie de imagen ni uses como descripción un nombre de archivo como screen-final-2.png.

Una imagen enlazada necesita un texto que comunique el destino o la acción del enlace, no solo su apariencia. Los separadores decorativos y los logotipos de marca repetidos deben tener el texto alternativo vacío cuando el renderizador lo permita, mientras que las insignias de estado deben recibir etiquetas concisas como Build: passing. Los comandos esenciales, la configuración o los mensajes de error también deben aparecer como texto seleccionable, porque las imágenes no permiten copiar, buscar, traducir ni ampliar el contenido de forma confiable.

Haz que los elementos gráficos funcionen con distintos temas y cuando falten recursos

Los logotipos y diagramas transparentes suelen presuponer un lienzo blanco. En un tema oscuro, los trazos negros pueden desaparecer; en uno claro, las etiquetas blancas pueden dejar de verse. Prueba ambos temas y agrega intencionalmente un fondo o un borde cuando un recurso pueda servir para los dos. Si el renderizador admite fuentes de imagen específicas para cada tema, mantén las versiones clara y oscura semánticamente equivalentes y proporciona una sola descripción alternativa útil para la imagen completa.

Diseña el párrafo circundante de modo que el README siga siendo comprensible mientras una imagen se carga o no está disponible. Nunca incluyas el único paso de instalación, una advertencia de seguridad o un requisito de compatibilidad únicamente dentro de una captura de pantalla. Evita transmitir significado solo mediante el color y revisa los diagramas con un nivel de zoom mayor. Estas prácticas favorecen la accesibilidad y también hacen que la documentación sea más resiliente en herramientas de solo texto, páginas de paquetes almacenadas en caché y redes restringidas.

Usa las insignias como resúmenes, no como fuente de verdad

Una insignia es una imagen generada de forma remota que resume datos cambiantes, como el resultado de una compilación, la versión de un paquete o el estado de cobertura. Su exactitud depende del servicio de origen, los parámetros de consulta, la selección de la rama, la autenticación, el almacenamiento en caché y el comportamiento de actualización. Enlaza la insignia a una página donde los lectores puedan inspeccionar el resultado subyacente y etiquétala para que su significado quede claro sin interpretar el color.

Mantén una selección limitada de insignias. Una larga secuencia de llamadas a servicios ralentiza el renderizado, genera ruido visual y aumenta la cantidad de partes contactadas cuando alguien abre el README. Nunca uses una insignia como único aviso de un problema de seguridad o de una versión compatible. Si un proveedor falla, la descripción del proyecto y el flujo de trabajo habitual de los colaboradores deben seguir teniendo sentido.

Revisa las imágenes como parte de las pruebas de la documentación

Previsualiza el README en el renderizador de GitHub después de crear un commit en una rama. Abre cada imagen, verifica las rutas relativas desde la ubicación real del README, cambia los temas de color e inspecciona los diseños estrechos y con zoom. Cuando el README se publique en un registro de paquetes o sitio de documentación, prueba también esa superficie, ya que las reglas de las URL relativas y el HTML compatible pueden variar.

Agrega comprobaciones operativas sencillas para los recursos importantes. Un verificador de enlaces puede detectar imágenes remotas faltantes, mientras que la revisión del repositorio puede identificar archivos binarios demasiado grandes y archivos fuente sin seguimiento. Revisa las capturas de pantalla cuando cambie la interfaz y elimina los recursos obsoletos solo después de buscar en todas las ramas de la documentación que aún se mantiene. El objetivo no es únicamente tener una imagen renderizada hoy, sino un documento comprensible durante toda la vida útil compatible del proyecto.