Respuesta rápida: ¿qué debe incluir una plantilla de GitHub Profile README?
Una plantilla de GitHub profile README sólida incluye una introducción breve, foco actual, proyectos seleccionados, stack técnico, enlaces de contacto o portfolio y pocas señales visuales, como badges, gráficos de contribuciones o un visual 3D.
Muchas búsquedas de awesome GitHub profile README o best GitHub profile README llevan a listas enormes de ejemplos. Sirven para inspirarse, pero no deciden qué conviene en tu perfil. Aquí la prioridad es la estructura y el límite entre contenido útil y ruido.
Si es tu primera vez, crea un repositorio público con el mismo nombre que tu usuario de GitHub, añade README.md y empieza con una versión simple. Tres proyectos fuertes suelen funcionar mejor que muchas animaciones y frases genéricas.
La intención de esta página es la plantilla del README. La guía de profile-3d-contrib cubre imágenes 3D automatizadas, y GitHub City cubre el visualizador interactivo.
Secciones de README que suelen merecer espacio
Piensa en el README de perfil como una landing page compacta. La primera mitad debe responder quién eres, qué construyes y dónde debe hacer clic el visitante.
No copies todas las secciones de una lista de inspiración. Un estudiante, una mantenedora open source y un freelance necesitan énfasis distintos.
| Sección | Propósito | Mantén | Evita |
|---|---|---|---|
| Frase inicial | Explica rol, foco o ruta de aprendizaje. | Una oración concreta con stack o dominio. | Afirmaciones genéricas sin prueba. |
| Proyectos destacados | Lleva al visitante al trabajo importante. | Dos a cuatro repos con resultado, stack y demo. | Listar todos los repositorios. |
| Habilidades | Muestra herramientas que realmente puedes explicar. | Grupos de lenguajes y frameworks relevantes. | Una pared de logos sin contexto. |
| Señal de actividad | Da contexto de constancia. | Contribution graph, GitHub City o imagen 3D con explicación. | Usar volumen de actividad como única prueba. |
| Prueba adicional | Añade profundidad más allá del código. | Artículos, charlas, docs o casos. | Enlaces sociales vacíos. |
| Contacto | Deja claro el siguiente paso. | Portfolio, email, LinkedIn o ruta específica. | Demasiados CTA compitiendo. |
Flujo de cinco pasos para construir la plantilla
La forma más fácil de terminar un profile README es separar planificación y decoración. Escribe primero el contenido; añade visuales solo donde aclaren.
También sirve para actualizar un perfil antiguo y eliminar badges rotos, imágenes pesadas o secciones que ya no representan tus objetivos.
Define el objetivo del visitante
Decide si el README busca empleo, credibilidad open source, clientes, aprendizaje o soporte de proyecto.
Redacta la estructura en texto
Escribe introducción, proyectos, stack y contacto antes de añadir gráficos.
Elige visuales útiles
Usa badges para datos rápidos, GitHub City para exploración 3D o profile-3d-contrib para una imagen de README.
Automatiza con cuidado
Las Actions son útiles si no generan ruido, rutas rotas o assets lentos.
Revisa en móvil y perfil real
Abre tu perfil público y comprueba tamaños, enlaces y claridad en la primera pantalla.
Ejemplos según el objetivo del perfil
La misma plantilla no sirve igual para todos. Elige el patrón según la decisión que debe tomar el lector.
Prioriza la prueba que quieres que recuerden: contratación, uso de paquete, colaboración o contacto.
Perfil para empleo
Rol, stack, dos proyectos fuertes, demos y contacto claro. Deja visuales de actividad debajo de la prueba.
Mantenedor open source
Paquetes mantenidos, guías de contribución, documentación, issues y soporte.
Estudiante o junior
Foco de aprendizaje, proyectos actuales, cursos y señal de progreso sin exagerar experiencia.
Creador o consultor
Resultados, casos, escritura, productos y una forma simple de iniciar conversación.
Cómo usar badges, stats y visuales 3D de contribuciones
Los visuales ayudan cuando reducen esfuerzo al lector. El problema aparece cuando el README queda dominado por widgets generados.
Usa GitHub City para una exploración interactiva de contribuciones. Usa github-profile-3d-contrib cuando necesitas una imagen 3D dentro del README.
Mantén alt text descriptivo, evita GIF grandes y no permitas que una tarjeta de estadísticas sea la única prueba de habilidad. Si tu sección de actividad usa un widget de racha, enlaza la guía de GitHub streak stats para explicar la tarjeta como señal visible, no como nota de productividad.
Regla simple
Si un visual no ayuda a decidir qué leer, abrir o confiar después, elimínalo o muévelo más abajo.
Revisión antes de publicar
Prueba el README como visitante público antes de darlo por terminado.
| Problema | Causa probable | Solución |
|---|---|---|
| Imagen rota | Ruta incorrecta, asset privado, rama renombrada o archivo no generado. | Abre la URL raw y verifica mayúsculas, rama y ruta. |
| Perfil lento | Demasiados badges remotos, GIF pesados o varias tarjetas. | Deja solo visuales esenciales y estáticos. |
| Sin siguiente paso | El README describe mucho pero no prioriza enlaces. | Coloca proyecto, portfolio o contacto arriba. |
| Actividad vacía | GitHub no contó commits o las contribuciones privadas están ocultas. | Revisa el gráfico oficial antes de culpar al widget. |
| Overflow móvil | Tablas anchas, badges sin salto o imágenes enormes. | Usa Markdown simple e imágenes menores. |
FAQ sobre plantillas de GitHub Profile README
¿Cómo agrego un README a mi perfil de GitHub?
Crea un repositorio público con el mismo nombre exacto que tu usuario y añade README.md. GitHub lo muestra en tu perfil.
¿Cuál es la mejor plantilla?
La que apoya tu objetivo actual: intro, proyectos, stack, señal de actividad, pruebas y contacto.
¿Conviene usar badges?
Sí, con moderación. Ayudan a escanear, pero una pared de badges reduce claridad.
¿Puedo añadir un gráfico 3D?
Sí. Usa profile-3d-contrib para una imagen automática o enlaza GitHub City para una ciudad 3D interactiva.
¿Debo incluir tarjetas de estadísticas?
Son opcionales y no sustituyen explicaciones de proyectos ni ejemplos reales.
¿Qué tan largo debe ser?
Cinco a ocho secciones enfocadas suelen bastar para muchos perfiles.