Qué hace GitHub README Stats
GitHub README Stats es un proyecto de código abierto que genera tarjetas SVG a partir de un nombre de usuario. La tarjeta principal puede mostrar estrellas, commits, pull requests, incidencias, repositorios con contribuciones y un rango; otra tarjeta resume los lenguajes usados.
Las cifras no son una evaluación completa de la capacidad técnica. La visibilidad de repositorios, la actividad privada, los forks, los archivos generados, la caché y los límites de API pueden cambiar el resultado. La tarjeta debe orientar al lector, no actuar como una puntuación profesional.
Coloca la tarjeta después de una introducción o de los proyectos destacados. Para necesidades concretas enlaza la guía de rachas, la guía de trofeos, la plantilla de README o la herramienta GitHub City.
Una tarjeta puede iniciar la conversación, pero los proyectos deben completarla. Explica el problema, tu papel, las decisiones técnicas y dónde revisar el código para que las estadísticas tengan sentido.
Cómo añadir y configurar una tarjeta
Empieza con la URL mínima, comprueba que carga y añade opciones de una en una para detectar parámetros incorrectos.
Abre el README de tu perfil
El repositorio público debe tener exactamente el mismo nombre que tu usuario. Coloca la tarjeta bajo la presentación o los proyectos.
Usa el usuario correcto
Sustituye el parámetro username en la URL oficial y abre primero la imagen directamente.
Elige un tema legible
Combina la tarjeta con el fondo real del README y prioriza el contraste en modo claro y oscuro.
Muestra métricas con sentido
Activa iconos u oculta datos solo cuando la decisión ayude a interpretar mejor el perfil.
Qué visual de perfil conviene usar
Cada recurso responde a una pregunta distinta. Elige un visual principal y, como máximo, uno de apoyo.
| Visual | Mejor uso | Configuración | Limitación | Ubicación |
|---|---|---|---|---|
| Tarjeta de estadísticas | Resumen general de actividad | URL con usuario y opciones | Necesita contexto | Tras la biografía |
| Lenguajes principales | Mezcla de lenguajes | Tarjeta separada | No mide habilidad | Junto a estadísticas |
| Rachas | Constancia reciente | Servicio de rachas | Sobrerrepresenta la actividad diaria | Solo si es relevante |
| GitHub City | Calendario 3D interactivo | Herramienta en el navegador | No sustituye proyectos | Enlace de exploración |
Problemas frecuentes
Los fallos suelen venir del usuario, la URL, la disponibilidad del servicio, la visibilidad o una interpretación incorrecta.
La tarjeta no carga
Abre la URL de imagen, revisa usuario y parámetros, elimina opciones y consulta el repositorio oficial.
Las cifras parecen bajas
Comprueba qué repositorios y contribuciones cuentan; la privacidad, los forks, la caché y la API influyen.
El tema se lee mal
Prueba la tarjeta sobre el fondo real y evita transparencias con poco contraste.
Los lenguajes engañan
Código generado, notebooks o un repositorio grande pueden dominar la distribución.
Construye el perfil con evidencias
Un buen perfil explica quién eres, qué construyes y dónde debe mirar el lector. Da prioridad a proyectos, resultados y código real; una tarjeta apoya esa historia, muchas tarjetas compiten con ella.
La guía de plantilla organiza el conjunto. GitHub City ofrece una vista memorable del calendario, pero el README debe explicar el trabajo que hay detrás.
Revisa el README con anchuras de escritorio y móvil. Evita filas demasiado anchas, dimensiones inestables y widgets que repiten la misma señal.
Antes de publicar, revisa la documentación actual del proyecto porque los parámetros disponibles y el comportamiento de la caché pueden cambiar. Guarda una versión sencilla de la URL que funcione y anota qué opción añade cada modificación. Si una combinación deja de responder, vuelve a la URL mínima en lugar de copiar configuraciones antiguas de otros perfiles.
Piensa también en accesibilidad y rendimiento. Usa texto alternativo útil, dimensiones estables y una distribución que no obligue a desplazarse horizontalmente. Una tarjeta externa puede tardar en cargar o fallar de forma temporal, por lo que la presentación y los enlaces a proyectos deben seguir siendo comprensibles aunque la imagen no aparezca.
No ocultes métricas solo para mejorar la apariencia del rango. Si excluyes un lenguaje o una cifra, hazlo porque distorsiona el propósito del perfil, por ejemplo código generado o un repositorio archivado. La edición debe ayudar al lector a interpretar los datos, no convertir la tarjeta en una afirmación más fuerte de lo que las fuentes permiten.
Combinación recomendada
Biografía breve, dos o tres proyectos destacados, una tarjeta de estadísticas y un visual opcional. Mantén el resto detrás de enlaces descriptivos.
Preguntas frecuentes
¿GitHub README Stats es oficial?
No. Es un proyecto de código abierto independiente que usa datos de GitHub para generar tarjetas.
¿Cómo añado estadísticas al README?
Edita el repositorio de perfil, inserta el Markdown de la imagen con tu usuario y revisa la vista previa.
¿Por qué faltan commits privados?
Depende de la configuración de visibilidad, los datos disponibles y las opciones del servicio.
¿Estadísticas, rachas o trofeos?
Usa estadísticas para el resumen, rachas para constancia y trofeos para hitos; no apiles todo.
¿Puedo combinarlo con GitHub City?
Sí. La tarjeta resume y GitHub City permite explorar el calendario de contribuciones en 3D.