¿Qué es un README de perfil de GitHub?
Un README de perfil de GitHub es un documento Markdown que se muestra en tu perfil público de GitHub cuando creas un repositorio público con el mismo nombre que tu usuario y añades un archivo README.md. En GitHub, ese repositorio especial te ofrece un lugar estable para explicar tu enfoque, mostrar trabajo seleccionado y dirigir a los visitantes hacia enlaces útiles.
La mejor primera versión no es una pared de insignias. Es una página breve y legible sobre tu trabajo en GitHub: una presentación de una frase, tu foco actual, dos o tres proyectos con pruebas y enlaces que ayuden al visitante a dar el siguiente paso. Puedes ampliarla después, cuando sepas qué información necesitan realmente las personas.
Esta página se centra en crear y publicar el README de perfil. Usa la guía de plantillas para la estructura, la guía de ideas para inspirarte y el generador para obtener un primer borrador copiable.
Qué necesitas antes de empezar
La configuración es sencilla, pero cada requisito importa. Un nombre parecido, la visibilidad privada o un archivo mal ubicado pueden hacer invisible un README correcto. Confirma lo básico antes de añadir colores, insignias o widgets.
Trata el repositorio del perfil como un pequeño proyecto público de GitHub: usa enlaces reales, deja claro el primer commit y nunca publiques secretos ni afirmaciones que no puedas respaldar. La documentación de GitHub es la autoridad final cuando cambia la interfaz.
| Requisito | Por qué importa | Ten en cuenta | Problema común |
|---|---|---|---|
| Nombre del repositorio | GitHub usa el repositorio que coincide con el usuario para identificar el README de perfil. | Copia tu nombre de usuario exacto, incluidos los signos y las mayúsculas cuando GitHub los requiera. | Crear un repositorio con el nombre visible, un apodo o un sufijo adicional. |
| Visibilidad pública | El README de perfil está pensado para que lo vean los visitantes del perfil. | Comprueba la visibilidad del repositorio antes de investigar el Markdown. | Dar por hecho que un repositorio privado se mostrará como contenido público del perfil. |
| README.md | El archivo Markdown es el documento que GitHub muestra en el repositorio y el perfil. | Coloca README.md en la raíz y conserva un nombre de archivo claro. | Guardarlo como README, readme.md en otra carpeta o como un archivo local que nunca se confirmó. |
| Primer borrador útil | Los visitantes necesitan contexto y pruebas antes de los elementos decorativos. | Empieza con una bio breve, tu foco, proyectos, enlaces y una acción siguiente. | Abrir con una fila interminable de insignias que oculte lo que realmente construyes. |
| Enlaces seguros | Un README de perfil es público y suele copiarse o compartirse. | Revisa URL, correos, imágenes, tokens y servicios incrustados antes de publicar. | Incluir secretos, paneles privados, enlaces que caducan o afirmaciones sin verificar. |
Cómo crear y añadir un README de perfil de GitHub
Puedes crear el README de perfil desde el flujo de nuevo repositorio de GitHub o subiendo un repositorio local. Lo importante es la relación entre el nombre del repositorio, su visibilidad pública y el archivo README.md. Sigue la secuencia para aislar un problema de configuración en lugar de adivinar con la sintaxis Markdown.
Cuando la primera versión esté publicada, trata las actualizaciones como trabajo normal de documentación. Previsualiza títulos y enlaces, abre el perfil público en una ventana sin sesión o privada cuando sea posible y elimina las secciones que ya no describan tu trabajo actual.
Confirma tu nombre de usuario exacto
Abre tu perfil de GitHub y copia el usuario de la URL del perfil. No te fíes solo del nombre del encabezado si es distinto del identificador de la cuenta.
Crea el repositorio público coincidente
Crea un repositorio nuevo con exactamente el mismo nombre que tu usuario. Déjalo público si quieres que cualquiera pueda ver el README de perfil e inicialízalo con un README o añádelo en el paso siguiente.
Escribe el archivo README.md
Empieza con una presentación corta, tu foco actual, proyectos seleccionados y enlaces útiles. Usa títulos y párrafos breves para que el visitante pueda escanear la página antes de decidir qué abrir.
Confirma y revisa la página pública
Confirma el README en la rama activa del repositorio, abre la página del repositorio y comprueba que el Markdown se muestra sin imágenes rotas, enlaces privados ni secretos accidentales.
Abre tu perfil y ajústalo
Vuelve a tu perfil público y verifica que aparece el README. Si no aparece, usa la lista de comprobación siguiente antes de cambiar el contenido o añadir más widgets.
Qué incluir en el README
Un README de perfil de GitHub debe responder cuatro preguntas rápidas: quién eres, en qué trabajas, qué puede revisar un visitante y adónde debe ir después. Elige secciones que demuestren o aclaren algo; no necesitas todos los widgets populares.
Usa los ejemplos siguientes como direcciones, no como promesas para copiar. Una frase sobre un proyecto es más fuerte cuando enlaza a un repositorio, demo, versión, artículo o captura que el lector pueda comprobar.
Una presentación de una línea
Explica tu rol o dirección con lenguaje sencillo. Sustituye las afirmaciones vagas por un foco concreto, como herramientas de datos, accesibilidad frontend o documentación open source.
Foco actual
Cuenta qué estás aprendiendo, publicando o manteniendo ahora. Esto pone un límite temporal al perfil y ayuda a entender qué proyectos siguen activos.
Proyectos seleccionados
Elige dos o tres repositorios y explica el problema, tu aportación y el resultado. Enlaza pruebas en lugar de enumerar cada experimento.
Enlaces útiles
Añade un portfolio, archivo de artículos, método de contacto o perfil de comunidad cuando sea público, actual y realmente útil para el lector.
Recursos visuales opcionales
Añade insignias, visualizaciones de contribuciones o estadísticas solo después de aclarar la historia principal, y elimina todo lo que esté obsoleto o sea puramente decorativo.
Usa plantillas, generadores y recursos visuales en el orden correcto
Una plantilla es útil cuando necesitas una estructura inicial, no cuando hace que todos los perfiles parezcan iguales. La guía de plantillas para README de perfil te ayuda a decidir qué secciones encajan y qué afirmaciones necesitan pruebas. El objetivo es un perfil que suene a ti y sea fácil de mantener después de la primera semana.
Un generador puede acelerar el primer borrador, pero no puede verificar tus proyectos ni decidir los límites de tu historia personal. Usa el generador de README en el navegador para obtener un esquema copiable y después edita el Markdown con tus repositorios reales. Si buscas ideas visuales, la guía de ideas para README de perfil es mejor lugar para comparar opciones que una colección aleatoria de insignias.
Regla sencilla
Publica primero el perfil útil y claro. Añade insignias, estadísticas o gráficos de contribuciones solo cuando cada elemento ayude al visitante a entender tu trabajo o elegir el siguiente paso.
Por qué no aparece tu README de perfil de GitHub
Cuando GitHub no muestra el README del perfil, revisa las condiciones de publicación antes de reescribir el contenido. La mayoría de los fallos son desajustes de nombre, visibilidad, ruta, rama o cuenta, no problemas de calidad del Markdown.
| Problema | Causa probable | Solución |
|---|---|---|
| El nombre del repositorio se parece, pero no es exacto | El repositorio se creó con un apodo, un nombre visible o un carácter adicional. | Compara el nombre del repositorio con el usuario de la URL de tu perfil y corrígelo si hace falta. |
| El repositorio es privado | La visibilidad cambió durante la configuración o el repositorio está dentro de una organización restringida. | Revisa la visibilidad y la política de la organización antes de esperar que lo vean los visitantes públicos. |
| El archivo no es README.md en la raíz | El archivo cambió de nombre, está en una carpeta o solo se guardó en tu ordenador. | Coloca README.md en la raíz, confírmalo en la rama activa y abre la página del repositorio para verificar el renderizado. |
| El perfil muestra una versión anterior | El último cambio no se confirmó, se subió a otra rama o el navegador muestra contenido en caché. | Comprueba el historial y la rama activa; después actualiza el perfil o ábrelo en una ventana privada. |
| Las imágenes o insignias están rotas | Se usa una ruta relativa, un recurso privado, una rama renombrada o una URL externa caducada. | Abre cada URL desde la página renderizada del repositorio y sustituye las fuentes inestables o privadas. |
| La página es difícil de leer | Hay demasiados widgets, párrafos largos o títulos que no corresponden al contenido. | Sube la presentación y las pruebas de proyectos, acorta las secciones y elimina bloques decorativos que no ayudan al visitante. |
Preguntas frecuentes sobre los README de perfil de GitHub
¿Es gratis un README de perfil de GitHub?
Sí. El README de perfil usa funciones de repositorios y Markdown de GitHub, así que puedes crearlo sin comprar una web o un plan de alojamiento aparte. Aun así, debes respetar la configuración de tu cuenta, organización y visibilidad del repositorio.
¿Cómo debe llamarse el repositorio del README de perfil?
Usa un nombre de repositorio que coincida exactamente con tu nombre de usuario de GitHub. Compara la URL del repositorio con la URL del perfil y no solo con el nombre visible en la interfaz.
¿Puede un repositorio privado alimentar un README de perfil?
Un repositorio privado no es una forma fiable de publicar un README de perfil para visitantes públicos. Comprueba la documentación actual de GitHub y la visibilidad del repositorio antes de investigar el Markdown.
¿Puedo usar un generador de README de perfil de GitHub?
Sí. Un generador puede ayudarte con un primer esquema o con la sintaxis Markdown, pero revisa cada frase, enlace de proyecto, imagen, insignia y afirmación frente a tu perfil real antes de publicar.
¿Qué debería evitar en un README de perfil?
Evita secretos, URL privadas, insignias obsoletas, animaciones excesivas, afirmaciones sin verificar y bloques largos que oculten tu trabajo actual. La documentación pública debe poder escanearse y compartirse con seguridad.