Cómo crear un README para destacar en GitHub

Portada » General » Cómo crear un README para destacar en GitHub

Si te paras a pensarlo, dos repositorios con el mismo código pueden transmitir sensaciones completamente distintas. Uno puede parecer un experimento olvidado y el otro un proyecto profesional, cuidado y listo para producción. La diferencia muchas veces no está en las líneas de código, sino en el README.

Un buen README es la cartelera de tu proyecto en GitHub: cuenta de qué va, por qué es interesante, cómo se usa y qué puede esperar quien llega desde cero. Cuando está bien trabajado, marca la diferencia ante recruiters, colaboradores potenciales y cualquiera que revise tu portfolio.

Qué es exactamente un README y por qué importa tanto en GitHub

Un README es un archivo de texto, normalmente llamado README.md, escrito en formato Markdown (o mezclando Markdown con HTML) que GitHub muestra automáticamente en la página principal del repositorio. Es, en la práctica, la puerta de entrada a tu proyecto.

Este archivo suele contener información clave sobre el proyecto: una descripción clara, para qué sirve, qué funcionalidades incluye, cómo se instala y ejecuta, quién lo ha desarrollado, qué licencia tiene y dónde encontrar ayuda o documentación adicional.

En GitHub, el README cumple una doble función: documentar el proyecto y venderlo. Documenta porque explica lo suficiente para que otra persona (o tú mismo dentro de seis meses) pueda entender qué hace y cómo usarlo. Y vende porque es el lugar donde puedes mostrar valor, cuidar el diseño, añadir imágenes, insignias y dejar buena impresión.

GitHub incluso te lo recuerda cuando subes un repositorio sin él: te recomienda explícitamente que añadas un README para ayudar a quienes se interesen por tu código a entender de qué va todo esto. Si usas GitHub como portfolio, este archivo se vuelve aún más crítico.

Conviene tener en mente que no todos los repositorios necesitan el mismo nivel de detalle. Para pruebas rápidas, scripts personales o proyectos que no quieras compartir, puedes permitirte un README mínimo o incluso prescindir de él. Pero en cuanto esperas visitas, feedback o quieres usarlo en tu CV, ya no es opcional.

Elementos imprescindibles que debe incluir un README potente

Cuando revisas proyectos de referencia de grandes organizaciones (por ejemplo, repositorios como los de Facebook o la propia NASA), se repiten ciertos patrones. No todos siguen la misma plantilla, pero sí comparten un conjunto de secciones que conviene tener presentes como base.

En general, un README sólido combina bloques obligatorios (lo mínimo para que cualquiera entienda el proyecto) y secciones adicionales que aportan contexto y profesionalidad. La mezcla de ambas partes es lo que hace que tu repositorio destaque.

Entre los elementos que más se ven en los mejores repositorios encontramos: título e imagen de portada, badges, índice, descripción del proyecto, estado, demo o capturas, acceso y despliegue, tecnologías, personas contribuyentes, autores y licencia. A partir de ahí puedes personalizar el orden y el estilo.

Piensa tu README como una historia que se lee de arriba abajo: primero engancha, luego aclara, después guía. No te limites a una lista desordenada de secciones; cuida la estructura y el flujo de lectura.

Título e imagen de portada: primera impresión que marca la diferencia

Lo primero que verá cualquiera al abrir tu repo es el título del README. Por defecto, GitHub usará el nombre del repositorio como encabezado, pero es buena idea cambiarlo por un título más descriptivo y legible, especialmente si el nombre del repo es corto o críptico.

En Markdown, los títulos se suelen crear con almohadillas, pero en un README puedes mezclar HTML para lograr cosas como centrar el título. Por ejemplo, podrías usar algo como <h1 align=»center»>Nombre descriptivo del proyecto</h1> en lugar de limitarte a la sintaxis más básica.

Después del título, muchos proyectos añaden una imagen de portada o un logo. Esta imagen puede ser un banner sencillo creado con herramientas como Canva, o un logotipo minimalista. Lo importante es que ayude a reforzar la identidad visual del proyecto y haga el README más atractivo de un solo vistazo.

Para incluir imágenes en el README puedes arrastrar el archivo directamente al editor de GitHub o usar la sintaxis de Markdown con la ruta de la imagen alojada en el propio repositorio o en un servicio externo fiable. Es recomendable incluir un texto alternativo descriptivo dentro del atributo alt para mejorar la accesibilidad.

Cómo usar badges para mostrar estado, versión y otros datos clave

Los badges son esas pequeñas insignias que se muestran al principio del README y que indican de un vistazo aspectos como el estado del proyecto, la licencia, la versión publicada, el estado de los tests o el número de estrellas. Aunque son elementos decorativos, aportan información muy útil en una fracción de segundo.

Muchas insignias se generan con servicios como Shields.io, que permite construir la URL de cada badge con el texto, color y estilo que quieras. Incluso puedes pegar la URL de tu repositorio y obtener sugerencias de insignias ya preparadas para tu caso.

Por ejemplo, un badge de estado del proyecto podría indicar si el repo está En desarrollo, En mantenimiento o Finalizado. Otro badge típico muestra la licencia (MIT, Apache 2.0, etc.), mientras que otros pueden mostrar el número de estrellas de tu cuenta o de ese repositorio en concreto.

La forma más habitual de añadirlos es mediante la sintaxis de imágenes en Markdown, pero si quieres alinearlos o agruparlos de manera más precisa puedes recurrir a etiquetas HTML como <p align=»center»> y colocar dentro las imágenes de los badges para que se vean centrados.

Índice y navegación: que nadie se pierda en tu README

En los README cortos, la navegación no suele ser un problema, pero a poco que documentes bien tu proyecto empiezan a aparecer varias secciones largas. En estos casos, un índice al principio ayuda muchísimo al lector a entender qué se va a encontrar.

GitHub crea de forma automática una tabla de contenido accesible desde un icono de esquema en la parte superior derecha del archivo, utilizando los distintos encabezados del documento. Aun así, incluir un índice manual en el propio texto es una buena práctica, porque permite saltar de forma directa a cada apartado con enlaces internos.

Para construir ese índice, basta con listar enlaces que apunten a los anchors generados por los encabezados. GitHub transforma los títulos en identificadores de sección de forma automática, siguiendo unas reglas claras: todo en minúsculas, espacios convertidos en guiones y caracteres especiales limpios.

Si quieres apuntar a una sección concreta cuya cabecera no te convence como ancla, también puedes usar anclas HTML personalizadas con <a name=»mi-ancla»></a> y enlazar a ellas con la sintaxis habitual de Markdown o con enlaces HTML.

Descripción del proyecto: qué hace y por qué debería importarle a alguien

Tras el título, la imagen y el índice, toca explicar el corazón del asunto: qué hace tu proyecto y cuál es su objetivo principal. Esta sección debería ser breve pero concreta, evitando tanto el exceso de jerga técnica como las descripciones vacías.

Una buena descripción responde, como mínimo, a tres preguntas: qué problema resuelve, a quién va dirigido y qué aporta frente a otras alternativas. Si el proyecto está inspirado en datos o casos reales (por ejemplo, estadísticas de uso o métricas de negocio), puedes mencionarlos para darle más peso.

También es buena idea separar una descripción funcional destinada al usuario final de una explicación más técnica pensada para desarrolladores, sobre todo en proyectos complejos. Así consigues que alguien no técnico entienda el objetivo, mientras que quien quiera contribuir dispone de más detalle.

Si se trata de un proyecto de portfolio, añade una o dos frases de contexto: por qué lo hiciste, qué tecnologías estabas aprendiendo y qué retos te planteaste. Esto ayuda a un reclutador a ver tu intención y tu nivel de autonomía.

Indicar el estado del proyecto: en desarrollo, estable o abandonado

Uno de los datos más útiles para cualquier persona que aterriza en un repo es saber si el proyecto está vivo o no. No es lo mismo encontrarse con algo en plena evolución que con un experimento sin mantenimiento desde hace años.

Puedes expresar el estado de varias formas: un badge en la cabecera, una pequeña sección explícita (“Estado del proyecto”) o ambas. Lo importante es que quede claro si está en construcción, estable, en modo mantenimiento o descontinuado.

Además del estado, algunos README incluyen notas sobre la estabilidad de la API, por ejemplo, avisando de que pueden producirse cambios rompientes o indicando a partir de qué versión se considera estable el contrato público.

No está de más acompañar este estado con algún emoji llamativo (por ejemplo, iconos de obra en construcción o de check) siempre que mantengas un tono profesional y no abuses de ellos en todo el documento.

Listar funcionalidades y mostrar una demo visual

Una de las secciones más revisadas de cualquier README es la que resume las funcionalidades principales del proyecto. Aquí es donde puedes desgranar de forma estructurada qué sabe hacer tu aplicación, biblioteca o API.

Resulta muy útil listar cada funcionalidad en viñetas y acompañarla de una breve descripción que explique el beneficio o el caso de uso. Por ejemplo, “Autenticación con OAuth2: permite a los usuarios iniciar sesión usando su cuenta de X” en lugar de limitarte a un nombre técnico poco claro.

Para ir un paso más allá, lo ideal es añadir una demostración visual: capturas de pantalla, un gif animado que muestre el flujo principal o incluso un enlace a un vídeo corto. Esto ayuda muchísimo a que alguien se haga una idea del proyecto sin necesidad de instalarlo.

Los gifs de flujo de uso suelen crearse con grabadores de pantalla que exportan directamente en ese formato, y se insertan exactamente igual que una imagen. Solo asegúrate de que el tamaño no sea exagerado para no ralentizar la carga del README.

Acceso, instalación y ejecución: cómo probar tu proyecto sin volverse loco

Por muy buena que sea la idea, si alguien no puede probar el proyecto con facilidad lo más probable es que abandone antes de tiempo. La sección de acceso e instalación debe dejar claro el camino para pasar del repositorio al código funcionando.

Si hay una versión desplegada online (por ejemplo, una SPA de React subida a un hosting estático o a GitHub Pages), pon el enlace bien visible y explícito. Es la forma más directa de permitir que alguien evalúe tu trabajo en segundos.

Cuando no exista demo pública, compénsalo con instrucciones claras para clonar el repositorio, instalar dependencias y arrancar el entorno. Indica los requisitos previos (versión de Node, Java, base de datos, etc.) y los comandos principales que hay que ejecutar.

A nivel de formato, es buena práctica usar bloques de código para los comandos de terminal y, si es necesario, separar las instrucciones para entorno de desarrollo y despliegue a producción. Cuanto menos tenga que adivinar el usuario, mejor.

Tecnologías empleadas: enseñar en qué stack te mueves

Otra sección casi obligatoria, especialmente si usas GitHub como portfolio, es el listado de tecnologías utilizadas en el proyecto. Aquí es donde dejas claro con qué lenguajes, frameworks y herramientas has trabajado.

Puedes presentarlo como una lista simple de texto (por ejemplo, “React, TypeScript, Vite, Jest, GitHub Actions…”), o darle un toque más visual con badges de tecnologías, iconos o logos, siempre cuidando que no se convierta en un collage difícil de leer.

Si el proyecto tiene parte de backend y frontend, puede ser buena idea separar las tecnologías por capas, para que se entienda la arquitectura: cliente, servidor, base de datos, infraestructura, testing, etc.

En repositorios de librerías o SDK, añadir versiones mínimas soportadas (por ejemplo, versión de Java, Python o Node) ahorra muchas dudas a otros desarrolladores que quieran integrarla.

Créditos, contribuciones y colaboradores

Cuando un proyecto tiene más de una persona involucrada, es de justicia y también de utilidad dedicar un espacio a reconocer a las personas contribuyentes. Esta sección suele llamarse “Contribuidores”, “Colaboradores” o similar.

Una forma muy vistosa de hacerlo es mostrar los avatares de GitHub de cada persona, su nombre y un enlace a su perfil. Esto no solo da crédito, sino que ayuda a otros a saber a quién dirigirse en caso de dudas concretas.

Además, muchos proyectos incluyen un enlace a una guía de contribución (por ejemplo, un archivo CONTRIBUTING.md) donde se explican las normas para colaborar: estilo de código, cómo abrir issues, cómo enviar pull requests, etc.

Si el proyecto es tuyo en solitario, puedes mantener igualmente un bloque de autores donde enlaces tu perfil de GitHub y, si te apetece, otra red profesional. Es un buen lugar para contar una o dos líneas sobre ti, especialmente en proyectos pensados para tu portfolio.

Licencia y aspectos legales básicos

La licencia es uno de esos apartados que a menudo se dejan para el final, pero que en realidad son fundamentales. Para que un proyecto pueda considerarse realmente de código abierto, debe tener una licencia explícita que indique qué se puede hacer con el código.

En el README conviene incluir una sección breve que indique qué licencia se aplica (MIT, Apache 2.0, GPL, Creative Commons para documentación, etc.) y, si procede, distinguir entre la licencia del código y la de la documentación o el contenido.

Lo habitual es tener un archivo LICENSE en la raíz del repositorio y enlazarlo desde el README. De esta forma, quien esté evaluando si puede usar o modificar tu proyecto tiene la información legal a mano sin tener que rebuscar.

Si por alguna razón todavía no has elegido licencia, indícalo de forma expresa para evitar malentendidos y plantéate resolverlo cuanto antes, ya que la ausencia de licencia limita muchísimo la reutilización de tu trabajo.

Cómo sacarle partido al README de tu perfil de GitHub

Además del README de cada repositorio, GitHub permite crear un README especial asociado a tu perfil que se muestra en la página principal de tu usuario. Es una especie de “landing personal” dentro de la plataforma.

Para activarlo, basta con crear un repositorio público cuyo nombre coincida exactamente con tu nombre de usuario y añadir un archivo README.md en la raíz. En cuanto tenga contenido, GitHub lo mostrará automáticamente en tu perfil.

Este README de perfil es un buen sitio para presentarte, enlazar tus proyectos más destacados, listar tecnologías que dominas, incluir estadísticas de contribuciones o incluso mostrar badges personalizados con información relevante.

Ten en cuenta que dejará de aparecer si borras el archivo, vacías su contenido, haces privado el repositorio o cambias el nombre del usuario o del repo de forma que ya no coincidan, así que conviene tratarlo como parte estable de tu identidad técnica.

Trucos de Markdown y HTML para dar estilo a tu README

GitHub usa una variante llamada GitHub Flavored Markdown, que añade algunas extensiones interesantes sobre la sintaxis clásica. Dominar lo básico te permitirá dar formato al texto sin romper la legibilidad ni desde el navegador ni desde un editor.

Para los encabezados, se usan de uno a seis símbolos de almohadilla para indicar el nivel, aunque siempre puedes mezclar con etiquetas HTML si necesitas más control. El uso correcto de títulos es lo que permite tener una tabla de contenido automática y anclas internas limpias.

El énfasis se marca con cursiva y negrita, que puedes conseguir con distintos delimitadores. Además, GitHub soporta elementos como subíndice, superíndice o texto subrayado mediante etiquetas HTML estándar, lo que abre la puerta a fórmulas, notas y matices visuales.

Si quieres resaltar citas, se emplean bloques de quote con el símbolo >, que GitHub representa con una barra vertical y un fondo diferenciado. Para fragmentos de código, puedes usar comillas invertidas simples dentro de una frase o bloques de código de varias líneas con triple comilla invertida, indicando si quieres el lenguaje para obtener resaltado de sintaxis.

Además, tienes a tu disposición listas ordenadas y desordenadas, listas anidadas, listas de tareas con casillas marcables, enlaces relativos dentro del propio repositorio y hasta alertas estilo admonición con una sintaxis especial de blockquote, muy útiles para remarcar notas importantes.

Imágenes, enlaces y recursos: cómo enriquecer el contenido sin liarla

Un README sin una sola imagen puede resultar árido, sobre todo cuando describes interfaces gráficas o flujos de uso. GitHub admite sin problema imágenes alojadas en el propio repositorio o en URLs externas, aunque siempre es más seguro tenerlas versionadas junto al código.

La sintaxis habitual combina el símbolo de exclamación con el texto alternativo entre corchetes y la URL entre paréntesis. También puedes construir rutas relativas para que el mismo README funcione desde distintas ramas o forks sin que se rompan las rutas.

Para los enlaces, la pauta es similar: texto descriptivo entre corchetes y URL a continuación. Es buena idea usar enlaces relativos cuando apuntes a otros archivos del repo (como CONTRIBUTING.md, docs adicionales, etc.), ya que se adaptan automáticamente a la rama en la que esté navegando la persona.

Si necesitas controlar el comportamiento o el estilo de un enlace o una imagen más allá de lo que permite Markdown, siempre puedes recurrir a etiquetas HTML completas. GitHub respeta muchas de ellas, incluyendo <a>, <img>, <picture> y comentarios HTML para ocultar secciones en la vista renderizada.

Listas, tareas y menciones: hacer tu README interactivo

Más allá del texto estático, GitHub integra algunas funciones sociales en los README y otros archivos Markdown que los vuelven más útiles y colaborativos. Por ejemplo, puedes mencionar a usuarios o equipos usando @ para llamar su atención sobre un fragmento o una sección.

También puedes hacer referencia a issues y pull requests con # seguido del número correspondiente, que se convierte automáticamente en un enlace abreviado, ideal para documentar cambios relevantes o vincular decisiones técnicas a debates previos.

Las listas de tareas con casillas marcables permiten mostrar de forma clara qué queda por hacer, y se actualizan visualmente cuando editas el README. Son muy útiles para construir un pequeño roadmap directamente visible en la página del proyecto.

Por último, la autocompletación de emojis y referencias hace que sea sencillo añadir un toque visual sin perder seriedad, siempre que mantengas un equilibrio y no conviertas el README en un festival de iconos.

Estructura mínima recomendada y extras para un README que destaque

Si un README pretende ser llamativo y profesional, hay una serie de bloques que conviene considerar casi obligatorios: un título claro, un índice, una explicación del funcionamiento, las tecnologías usadas, capturas o vídeos, instrucciones de instalación y un roadmap básico.

El roadmap no tiene por qué ser gigantesco; basta con una lista de próximas mejoras o ideas pendientes que indiquen hacia dónde te gustaría llevar el proyecto. A ojos de un reclutador, demuestra que piensas en la evolución del producto y no solo en la funcionalidad mínima.

Sobre esa base, puedes añadir secciones adicionales que enriquecen mucho el conjunto: motivación personal, secciones de agradecimientos, estructura de carpetas generada con herramientas como extensiones de árbol de proyecto, y cualquier otro detalle que ayude a entender mejor el código.

La clave está en que cada extra sume claridad o contexto. Si algo solo ocupa espacio pero no aporta información práctica, es mejor simplificar. Un README excelente suele ser extenso, sí, pero también muy fácil de escanear y navegar.

Cuando inviertes un rato en pulir el README de ese proyecto React que acabas de terminar, en documentar bien cómo se arranca, en listar las librerías clave y en explicar por qué tomaste ciertas decisiones, estás haciendo mucho más que “rellenar” un archivo: estás convirtiendo tu código en un producto entendible y atractivo para cualquiera que se pase por tu GitHub, lo que multiplica tus opciones de destacar frente a otros perfiles con repositorios huérfanos de documentación.