Rendimiento multimedia # Añadir imágenes e insignias a un README de GitHub: cuatro formas Agrega imágenes a un README de GitHub mediante archivos del repositorio, adjuntos de incidencias, URL sin procesar, HTML o recursos generados. Publicado el 11 de agosto de 2026 ## Conclusiones clave * Las rutas relativas del repositorio mantienen la documentación y sus recursos versionados en conjunto. * Las URL de las subidas realizadas en incidencias son prácticas, pero su auditoría y migración resultan menos evidentes. * Las URL externas reducen el tamaño del repositorio, pero introducen otra dependencia de disponibilidad y privacidad. Las imágenes de un README pueden estar en el repositorio, usar una URL de archivo adjunto de GitHub, hacer referencia a almacenamiento público o usar HTML para disponer de un control limitado sobre la disposición. La mejor opción depende de la propiedad, el control de versiones, la portabilidad y la frecuencia de actualización. ## En esta guía 1. [Elige la ubicación de la imagen según su propiedad y vida útil](#images-in-github-readmes-section-1) 2. [Conserva en el repositorio los recursos específicos de cada versión](#images-in-github-readmes-section-2) 3. [Trata los archivos adjuntos y las imágenes remotas como dependencias externas](#images-in-github-readmes-section-3) 4. [Usa Markdown para el significado y HTML solo cuando necesites controlar la disposición](#images-in-github-readmes-section-4) 5. [Prepara las imágenes para el tamaño en que se leerán](#images-in-github-readmes-section-5) 6. [Escribe el texto alternativo según la función de la imagen](#images-in-github-readmes-section-6) 7. [Haz que los elementos gráficos funcionen con distintos temas y cuando falten recursos](#images-in-github-readmes-section-7) 8. [Usa las insignias como resúmenes, no como fuente de verdad](#images-in-github-readmes-section-8) 9. [Revisa las imágenes como parte de las pruebas de la documentación](#images-in-github-readmes-section-9) ## Lo más importante * El marcado HTML de imágenes permite definir dimensiones, aunque GitHub sanea los elementos y atributos no compatibles. * Las insignias de estado generadas son útiles cuando se comprende su servicio y su comportamiento de respaldo. ## 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. ### Archivo del repositorio Es la mejor opción para recursos que deben revisarse, versionarse y publicarse con la documentación. ### Archivo adjunto de GitHub Resulta práctico para discusiones y contenido multimedia ocasional en el README, pero su propietario y su ruta de migración son menos visibles que los de un archivo registrado. ### URL externa Resulta útil para recursos gestionados de forma centralizada o que cambian con frecuencia, aunque añade una dependencia de disponibilidad, privacidad y control de acceso. ### Imagen generada Es adecuada para información de estado no esencial cuando los lectores aún pueden comprender el proyecto si el generador no está disponible. ## 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. ### Ruta relativa Por lo general, es la referencia más fácil de mantener para una imagen confirmada en el repositorio junto con el README. ### URL de la rama predeterminada Siempre sigue esa rama, lo cual resulta útil para la documentación actual, pero puede hacer que las referencias antiguas muestren imágenes más recientes. ### URL fijada a un commit Ofrece una vista inmutable para lanzamientos o auditorías, pero requiere actualizaciones deliberadas cuando cambia la imagen. ## 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. Preferir Markdown conciso para una imagen de contenido ``` ![Diagram showing the request flow from the browser through the API to object storage](docs/request-flow.png) ``` Usar HTML solo cuando el diseño del README lo requiera ```

Dashboard showing three completed uploads

``` ## 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. ### Recortar primero Elimina la interfaz del navegador, los márgenes vacíos y las áreas no relacionadas de la aplicación antes de redimensionar. ### Conservar la legibilidad Revisa las etiquetas pequeñas, el texto de la terminal y las líneas delgadas de los diagramas en el ancho de visualización final. ### Eliminar metadatos sensibles Inspecciona los nombres de archivo, los metadatos incrustados, los datos visibles de las cuentas, los tokens de acceso y las notificaciones antes de crear el commit. ### Controlar el crecimiento del repositorio Reemplazar un archivo binario grande no elimina sus versiones anteriores del historial de Git, así que optimízalo antes del primer commit. ## 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. ### Renderizado Verifica la página del repositorio, las bifurcaciones, las etiquetas de las versiones, los espejos de paquetes y toda documentación generada que utilice el README. ### Accesibilidad Revisa el texto alternativo, el contraste del texto, el comportamiento de los temas, el zoom y si la información esencial está disponible fuera de las imágenes. ### Rendimiento Revisa las dimensiones codificadas, el tamaño de transferencia, la cantidad de insignias y si son necesarias varias capturas de pantalla a resolución completa. ### Gobernanza Confirma la propiedad, la licencia, la fuente editable, la responsabilidad de actualización y un plan de migración para los recursos alojados externamente. ## Detalles técnicos que conviene conocer * Las URL relativas de las imágenes se resuelven de manera diferente en una página de repositorio, un registro de paquetes, un archivo Markdown copiado y un renderizador externo de documentación, por lo que debe probarse su portabilidad. * El texto alternativo debe comunicar el propósito de la imagen sin repetir el pie de imagen cercano; las insignias de estado pueden usar etiquetas concisas como «Build: passing» en lugar de nombres de archivo extensos. * Las insignias son imágenes generadas de forma remota cuya disponibilidad, almacenamiento en caché, privacidad y exactitud dependen de otro servicio, lo que las hace inadecuadas para información esencial del proyecto. * Las imágenes alojadas en el repositorio se versionan junto con el proyecto, pero los enlaces a una rama pueden cambiar, mientras que los enlaces a un commit son inmutables y más difíciles de mantener. * Las capturas de pantalla grandes ralentizan las páginas y las clonaciones del repositorio cuando se incluyen directamente en un commit, por lo que deben considerarse las dimensiones, la compresión, la frecuencia de actualización y la ubicación de almacenamiento. * Los temas oscuro y claro de GitHub pueden volver ilegibles los logotipos o diagramas transparentes; las consultas de medios del elemento picture pueden proporcionar imágenes específicas para cada tema cuando exista soporte. ## Un enfoque práctico 1. 1\ Define la propiedad y la vida útil del recurso antes de seleccionar la URL de Markdown. 2. 2\ Cambia el tamaño de las capturas de pantalla para ajustarlas a un ancho de lectura útil y optimízalas sin desenfocar el texto. 3. 3\ Escribe un texto alternativo conciso y usa un nombre de archivo descriptivo. 4. 4\ Previsualiza el README en el renderizador de GitHub y verifica los enlaces desde bifurcaciones y espejos de paquetes. Un flujo de trabajo multimedia de cuatro etapas ## Límite de la arquitectura GitHub controla el renderizado del README y los permisos del repositorio. Las herramientas de procesamiento de imágenes pueden preparar archivos antes de confirmarlos o enlazarlos, pero no los suben al historial de Git ni gestionan los archivos adjuntos de GitHub. ## Preguntas frecuentes ### ¿Las imágenes de un README deben usar URL relativas o absolutas? Usa rutas relativas para los archivos versionados con el repositorio, ya que normalmente siguen las ramas y bifurcaciones. Usa una URL HTTPS absoluta cuando otro sistema sea deliberadamente el propietario del recurso. Prueba cualquiera de las formas en cada renderizador importante, ya que los sitios de paquetes y el Markdown copiado pueden resolver las rutas de manera diferente. ### ¿Se puede cambiar el tamaño de una imagen de un README con Markdown? Markdown básico no ofrece una sintaxis portátil para definir tamaños. Cuando sea necesario especificarlos, usa un elemento HTML `img` sencillo con `width` y `height` y luego previsualiza el resultado en GitHub. Optimiza también el archivo de origen, porque las dimensiones de visualización no reducen los bytes descargados. ### ¿Incrustar una imagen como base64 es una buena forma de evitar enlaces rotos? Por lo general, no. Base64 dificulta la lectura y revisión del README, aumenta el tamaño de su texto, reduce la flexibilidad del almacenamiento en caché y algunos renderizadores pueden rechazarlo. Es más fácil mantener un archivo de imagen incluido en el repositorio o una URL pública gestionada de forma deliberada. ### ¿Son seguras las imágenes de un README alojadas externamente para los repositorios privados? No lo des por sentado. GitHub obtiene y almacena en caché las imágenes renderizadas mediante su proxy de anonimización, por lo que las imágenes que necesitan cookies o una red privada no se mostrarán. Otros renderizadores pueden permitir que los lectores contacten directamente al host, y una URL pública puede exponer un recurso independientemente de los permisos del repositorio. Evita el contenido confidencial, usa un host aprobado y comprende cómo gestiona GitHub actualmente las imágenes antes de insertar recursos de terceros. ### ¿Cómo deben gestionarse las capturas de pantalla que contienen datos de una cuenta? Cuando sea posible, realiza la captura desde una cuenta de prueba específica. Recorta las áreas no relacionadas, oculta los tokens y la información personal, revisa las notificaciones y la interfaz del navegador, y elimina los metadatos sensibles. Cubre el texto sensible con bloques opacos en lugar de desenfocarlo o pixelarlo, porque a veces es posible reconstruir los caracteres ocultos a partir de los píxeles publicados y los detalles subyacentes también pueden permanecer en los archivos de origen o en el historial de edición. Rendimiento multimedia ## Continúa con guías relacionadas * [Cinco mejores prácticas para imágenes de fondo en HTML y CSS](/es/guides/html-background-image-best-practices.md)\ Cinco prácticas para imágenes de fondo CSS que equilibran la composición, la accesibilidad y el rendimiento de la página. * [Cinco formas de usar imágenes en React, desde la importación estática hasta las subidas del usuario](/es/guides/import-images-in-react.md)\ Compara importaciones estáticas, rutas públicas, URL remotas, importaciones de CSS y resultados de subidas en tiempo de ejecución en React. * [Seis formas confiables de guardar imágenes en Python](/es/guides/save-images-in-python.md)\ Guarda imágenes desde bytes, URL, Pillow, OpenCV, subidas y resultados de procesamiento gestionado sin perder el manejo de errores. * [Ocho prácticas para optimizar el SEO de imágenes](/es/guides/image-seo-optimization.md)\ Ocho prácticas de SEO para imágenes sobre semántica, dimensiones, formatos, rendimiento, descubrimiento y medición. * [Cómo servir imágenes responsivas desde una sola URL](/es/guides/serve-responsive-images-from-one-url.md)\ Genera cada tamaño de imagen desde una URL canónica, almacena los resultados en caché perimetral y mantén estable el costo de codificación al crecer el tráfico.