¿Qué hace útil a un badge del README de GitHub?
Un badge para README de GitHub es una imagen pequeña, normalmente cerca del título del proyecto, que comunica un dato verificable. El estado de la compilación, la versión, la licencia, la documentación y la cobertura son ejemplos comunes. La imagen no es la prueba completa: el enlace de origen permite revisar la afirmación.
Los mejores badges reducen la incertidumbre de quien decide instalar, usar, contribuir o confiar en un repositorio. Un badge de workflow puede indicar si las comprobaciones principales están verdes; uno de release puede mostrar si el proyecto sigue activo; uno de licencia ayuda a localizar las condiciones de reutilización.
No confundas los badges del README con GitHub Achievements, Profile Trophy o los gráficos de contribuciones. Son señales distintas. La guía de GitHub Achievements cubre las insignias oficiales, mientras que la guía de ideas para Profile README explica cuándo un badge apoya la historia del perfil sin sustituir la evidencia del proyecto.
Una regla práctica: la primera fila debe poder escanearse desde un teléfono. Si el visitante tiene que atravesar diez badges antes de llegar a la explicación del proyecto, la decoración está ocultando el trabajo. Conserva primero los datos que cambian la siguiente decisión y deja lo opcional más abajo.
Sintaxis Markdown para badges de GitHub
La mayoría de los badges para README de GitHub usa la sintaxis normal de imágenes Markdown. Primero aparece la URL de la imagen; el envoltorio de enlace es opcional, pero hace que el badge sirva para abrir la fuente. Mantén un texto alternativo corto y claro para cuando la imagen no cargue.
Shields.io puede generar badges desde servicios compatibles o desde una etiqueta y un valor fijos. Usa el formato documentado por el proveedor y no adivines parámetros. Si un servicio cambia su API, una URL inventada puede producir una imagen rota o un dato desactualizado.
El ejemplo enlaza un badge de compilación con la página del workflow. Sustituye el repositorio y el endpoint por los de tu proyecto y abre el README sin iniciar sesión para comprobar que la imagen y el destino son públicos.
[](https://github.com/your-name/your-repo/actions)| Tipo | Fuente Markdown típica | Qué debería demostrar |
|---|---|---|
| Compilación | endpoint de workflow o CI | Si el workflow revisado pasa para la rama o el contexto indicado. |
| Release | última release o versión del paquete | Qué versión debe revisar o instalar el lector. |
| Licencia | badge de licencia del repositorio | Dónde consultar los permisos antes de reutilizar el código. |
| Documentación | enlace a docs o referencia API | Un camino directo a la configuración y el uso. |
| Cobertura | endpoint de un servicio de cobertura | Una señal de pruebas solo si la métrica se mantiene y se entiende. |
Flujo de mantenimiento para badges del README
Añadir badges es fácil; mantenerlos correctos es el trabajo real. Revisa la fila cuando cambien el proveedor, la rama, el nombre del paquete, el proceso de release, la documentación o la licencia. Un badge que era correcto hace seis meses puede resultar engañoso después de una migración.
Antes de añadir una imagen, escribe la frase que debe apoyar. Si la frase es «se ve profesional», probablemente el badge sobra. Si es «el lector puede confirmar la versión actual sin buscar por todo el repositorio», el badge sí tiene una función clara.
La guía de plantilla de Profile README ayuda a ordenar la evidencia del proyecto y los elementos visuales. Si colocas badges junto a tarjetas de actividad, consulta también la guía de GitHub README Stats para no repetir la misma señal.
Elige la pregunta del lector
Decide si el badge responde sobre compilación, release, licencia, documentación, compatibilidad o calidad. No empieces por una colección de colores.
Encuentra la fuente de verdad
Usa el workflow oficial, el registro de paquetes, el archivo de licencia, la documentación o un proveedor mantenido. La fuente debe ser pública y comprensible.
Añade imagen y enlace
Usa sintaxis Markdown, un alt útil y un enlace a la evidencia. Mantén el código legible para la siguiente persona que lo mantenga.
Revisa el README renderizado
Abre la página del repositorio y el README sin iniciar sesión. Comprueba imágenes, destinos, contraste y ajuste en una pantalla estrecha.
Revisa después de cambios
Vuelve a comprobar los badges al cambiar ramas, CI, paquetes, releases, documentación o licencia. Elimina los que estén obsoletos.
¿Qué badges para README de GitHub conviene elegir?
No existe un conjunto universal. La combinación depende de la decisión que el lector necesita tomar. Una biblioteca puede usar release, paquete, licencia, documentación y CI; un proyecto de portfolio puede necesitar demo, despliegue y una nota técnica breve; un experimento privado puede no necesitar ninguna fila de badges.
Mantén el límite temático en los badges de README. Los badges de repositorio, los logros del perfil, Profile Trophy, los gráficos de contribuciones y README Stats tienen intenciones distintas y deben seguir siendo guías separadas o enlaces de apoyo.
Estado de compilación
Úsalo cuando las pruebas o el despliegue importen. Enlaza a checks o workflow, no solo a la portada del repositorio.
Release o paquete
Muestra una fuente actual cuando el lector necesita saber qué instalar o revisar. Evita mantener el número en dos lugares.
Licencia
Conserva el badge cuando los permisos de reutilización importen y enlaza al archivo de licencia real.
Documentación
Es útil para bibliotecas, APIs y herramientas si lleva a una guía de inicio o referencia mantenida.
Cobertura o calidad
Muestra la métrica solo cuando su significado es claro y el proveedor es estable; un número sin contexto reduce confianza.
Solución de problemas de badges del README
Cuando un badge no se muestra o deja de decir la verdad, revisa la fuente antes de cambiar de proveedor. Estas comprobaciones cubren los fallos Markdown y de mantenimiento más comunes.
| Problema | Causa probable | Solución |
|---|---|---|
| La imagen está rota | Cambió el endpoint, la ruta, la consulta o el proveedor. | Abre la URL directamente, consulta la documentación y actualiza o elimina el badge. |
| La imagen está desactualizada | Se dejó un valor manual o una URL de release antigua. | Apunta a una fuente viva y compárala con la página de release, workflow o paquete. |
| El enlace abre otra página | Se copió el envoltorio Markdown de otro repositorio. | Prueba el destino sin iniciar sesión y enlaza la evidencia exacta. |
| La fila ocupa demasiado en móvil | Hay demasiados badges, etiquetas largas o una tabla ancha. | Conserva los más útiles, mueve detalles abajo y prueba una pantalla estrecha. |
| El dato privado no aparece | El proveedor no puede leer un repositorio privado. | Usa una fuente pública, explica el límite o elimina el badge. |
| El README parece un marcador | Se repiten badges, stats, streaks y logros sin explicar su función. | Pon la evidencia del proyecto primero y conserva solo señales diferentes. |
Preguntas frecuentes sobre badges de GitHub
¿Cómo añado badges a un README de GitHub?
Añade una imagen Markdown y, si procede, envuélvela en un enlace hacia el workflow, release, licencia o documentación. Después revisa la página del repositorio publicada.
¿Cuáles son los mejores badges para un proyecto?
Elige los que respondan a una duda real: compilación, release, paquete, licencia, documentación o una métrica mantenida. La mejor fila suele ser corta.
¿Puedo añadir badges a un Profile README?
Sí, pero deben quedar por debajo de tu identidad y de la evidencia de tus proyectos. La guía de ideas para Profile README explica cómo evitar una pared de widgets.
¿Los badges del README son GitHub Achievements?
No. Los primeros son imágenes Markdown elegidas por el autor; Achievements son insignias oficiales del perfil que administra GitHub.
¿Debo usar Shields.io para todos los badges?
No. Úsalo para endpoints documentados y estables, pero conserva un proveedor oficial cuando la fuente sea más clara y evita duplicar el mismo dato.
¿Cuántos badges debe tener un README?
No hay una cifra fija. Empieza con el conjunto mínimo que ayude a instalar, confiar o contribuir, y elimina lo decorativo, duplicado o difícil de verificar.