Hay proyectos en GitHub con código brillante que nadie usa. Y proyectos con código mediocre que tienen miles de estrellas y contribuidores. La diferencia muchas veces no está en el código — está en el README.
El README es la portada de tu proyecto. Es lo primero que ve cualquier persona que llega a tu repositorio, sea un recruiter evaluando tu portfolio, un desarrollador buscando una librería o un posible colaborador. Tienes menos de 10 segundos para captar su atención antes de que cierre la pestaña.
En este artículo vas a aprender a escribir un README profesional que destaque: estructura correcta, Markdown avanzado, badges de shields.io, GIFs de demo, tabla de contenidos, y el README especial de tu perfil personal en GitHub. Con plantillas reales que puedes copiar y adaptar.
Si quieres dominar también el flujo de trabajo con Git para gestionar tus proyectos, échale un vistazo a nuestro artículo sobre ramas, merges y pull requests en Git.
¿Qué es un README y por qué importa tanto?
Un README (léase "read me" — léeme) es un archivo de texto en formato Markdown (README.md) que GitHub muestra automáticamente en la página principal de cualquier repositorio. Es literalmente lo primero que cualquier visitante ve.
Un estudio analizado en la comunidad de GitHub indica que los proyectos con README completos y bien estructurados reciben significativamente más estrellas, forks y contribuciones que los que tienen un README vacío o descuidado. La razón es simple: si no explicas qué hace tu proyecto ni cómo usarlo, nadie va a tomarse la molestia de descubrirlo por su cuenta.
Un README responde a tres preguntas fundamentales:
1. ¿QUÉ hace este proyecto?
→ La descripción debe ser clara en menos de 2 frases
2. ¿POR QUÉ debería usarlo?
→ El valor diferencial frente a otras alternativas
3. ¿CÓMO se instala y usa?
→ Los pasos exactos, sin asumir nada del lectorMarkdown en GitHub (GFM) — lo que necesitas saber
GitHub usa una versión extendida de Markdown llamada GitHub Flavored Markdown (GFM). Tiene características adicionales que no están en el Markdown estándar y que hacen los READMEs mucho más potentes.
# Encabezados — jerarquía visual
# H1 — título principal (uno solo por README)
## H2 — sección principal
### H3 — subsección
#### H4 — subsección de subsección
# Énfasis de texto
**negrita**
*cursiva*
~~tachado~~
`código en línea`
> Cita o nota destacada
# Listas
- Elemento no ordenado
- Subelemento (sangría de 2 espacios)
- Otro elemento
1. Elemento ordenado
2. Segundo elemento
1. Subelemento numerado
# Listas de tareas (solo GFM)
- [x] Tarea completada
- [ ] Tarea pendiente
- [ ] Otra tarea pendiente
# Código — bloques con resaltado de sintaxis
```python
def hola_mundo():
print("¡Hola desde Python!")
```
```bash
pip install mi-libreria
python app.py
```
```javascript
const api = require('mi-api');
api.start();
```
# Tablas (solo GFM)
| Columna 1 | Columna 2 | Columna 3 |
|-----------|-----------|-----------|
| valor A | valor B | valor C |
| valor D | valor E | valor F |
# Alineación en tablas
| Izquierda | Centro | Derecha |
|:----------|:--------:|----------:|
| texto | texto | texto |
# Imágenes
# Imagen con enlace
[](https://mi-proyecto.com)
# Línea horizontal
---
# Notas y advertencias (GFM moderno)
> [!NOTE]
> Información útil que el usuario debe conocer.
> [!WARNING]
> Acción que puede tener consecuencias no deseadas.
> [!IMPORTANT]
> Información crítica para el uso correcto.
> [!TIP]
> Consejo para mejorar la experiencia.La estructura ideal de un README — sección por sección
1. Título y descripción — los primeros 3 segundos
# 🚀 NombreDelProyecto
> Una frase que explica exactamente qué hace el proyecto en menos de 15 palabras.
Descripción expandida (2-3 frases máximo): qué problema resuelve, para quién
está diseñado y qué lo hace diferente de las alternativas existentes.
**Ejemplo malo:**
# mi-api
Una API creada con Node.js
**Ejemplo bueno:**
# 📦 StockAlert API
> API REST para monitorizar stock de productos y enviar alertas automáticas
> por email cuando el inventario cae por debajo del umbral configurado.
Diseñada para tiendas online que usan sistemas de inventario externos y
necesitan notificaciones en tiempo real sin depender de un panel de administración.2. Badges — credibilidad de un vistazo
Los badges son esas pequeñas etiquetas visuales que ves en los proyectos populares. Se generan con shields.io y muestran información del proyecto en tiempo real.
# Sintaxis de un badge:
# Badges estáticos (con texto personalizado):
# Badges dinámicos conectados a tu repositorio real:
# Badges de CI/CD (GitHub Actions):
# Badges de tecnologías (con logos):
# Cómo se ven en el README (línea de badges):
[](CHANGELOG.md)
[](LICENSE)
[](acciones)
[]()💡 Regla de los badges: 3-5 badges son suficientes. Más de 8 genera ruido visual. Prioriza los que aportan información real: licencia, versión, estado del CI y tecnología principal.
3. Demo visual — una imagen vale más que mil palabras
# Captura de pantalla estática
# GIF animado mostrando la funcionalidad principal (el más efectivo)
# Para crear GIFs: usa LICEcap (Windows/Mac) o Peek (Linux)
# Vídeo (GitHub permite embeber vídeos mp4 directamente)
https://user-images.githubusercontent.com/xxxxx/tu-video.mp4
# O enlace a demo en vivo
## 🌐 [Ver demo en vivo →](https://mi-proyecto.vercel.app)
# Badge con enlace a demo
[](https://mi-proyecto.vercel.app)4. Tabla de contenidos — para READMEs largos
## 📋 Tabla de Contenidos
- [Características](#características)
- [Instalación](#instalación)
- [Uso rápido](#uso-rápido)
- [Configuración](#configuración)
- [API Reference](#api-reference)
- [Contribuir](#contribuir)
- [Licencia](#licencia)
# Los enlaces se generan automáticamente a partir de los encabezados:
# El texto del enlace en minúsculas, espacios → guiones, sin caracteres especiales
# "Uso Rápido" → #uso-rápido
# "API Reference" → #api-reference5. Características — qué hace y por qué es especial
## ✨ Características
- 🚀 **Rendimiento optimizado** — procesa 10,000 registros por segundo
- 🔒 **Seguridad** — autenticación JWT con rotación automática de tokens
- 📊 **Dashboard en tiempo real** — métricas actualizadas con WebSocket
- 🌐 **API REST completa** — documentación OpenAPI/Swagger incluida
- 🐳 **Listo para Docker** — imágenes disponibles en Docker Hub
- 🧪 **100% testeado** — cobertura completa con Jest y Supertest
- 📱 **Responsive** — optimizado para móvil, tablet y escritorio6. Instalación y uso rápido — lo más importante
## 🚀 Instalación
### Prerrequisitos
- Node.js 22 o superior
- PostgreSQL 16
- Docker (opcional)
### Instalación rápida
```bash
# Clonar el repositorio
git clone https://github.com/tu-usuario/mi-proyecto.git
cd mi-proyecto
# Instalar dependencias
npm install
# Copiar el archivo de variables de entorno
cp .env.example .env
# Edita .env con tus credenciales
# Inicializar la base de datos
npm run db:migrate
# Iniciar en modo desarrollo
npm run dev
```
### Con Docker
```bash
docker compose up -d
# La aplicación estará disponible en http://localhost:3000
```
## 📖 Uso rápido
```javascript
const StockAlert = require('stockalert-api');
const client = new StockAlert({
apiKey: process.env.STOCKALERT_KEY
});
// Configurar alerta cuando el stock baje de 10 unidades
await client.alerts.create({
productId: 'PROD-001',
threshold: 10,
email: 'admin@tienda.com'
});
```7. Configuración — el .env explicado
## ⚙️ Configuración Copia `.env.example` a `.env` y configura las variables: ```env # Base de datos DATABASE_URL=postgresql://usuario:contraseña@localhost:5432/stockalert # Servidor PORT=3000 NODE_ENV=development # Autenticación JWT_SECRET=tu-secreto-muy-largo-y-aleatorio JWT_EXPIRES_IN=7d # Email (para las alertas) SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_USER=tu@gmail.com SMTP_PASS=tu-app-password ```
8. Sección de contribución
## 🤝 Contribuir
Las contribuciones son bienvenidas. Para cambios importantes, abre
primero un issue para discutir qué te gustaría cambiar.
1. Haz fork del repositorio
2. Crea tu rama: `git checkout -b feature/nueva-funcionalidad`
3. Haz commit de tus cambios: `git commit -m 'feat: añadir nueva funcionalidad'`
4. Sube la rama: `git push origin feature/nueva-funcionalidad`
5. Abre un Pull Request
Por favor, asegúrate de actualizar los tests según corresponda.
## 🐛 Reportar bugs
¿Encontraste un bug? Abre un [issue](https://github.com/usuario/repo/issues/new)
con:
- Descripción del problema
- Pasos para reproducirlo
- Comportamiento esperado vs actual
- Versión del proyecto y sistema operativo9. Licencia y créditos
## 📄 Licencia Este proyecto está bajo la [Licencia MIT](LICENSE). ## 👏 Créditos - Inspirado en [proyecto-similar](https://github.com/...) - Usa [librería-externa](https://npm.js/librería) para el procesamiento - Iconos de [Feather Icons](https://feathericons.com/)
Plantilla completa — cópiala y adapta
# 🚀 Nombre del Proyecto
> Descripción de una línea: qué hace y para quién.
[](CHANGELOG.md)
[](LICENSE)
[]()
## ✨ Características
- 🚀 **Característica 1** — descripción breve
- 🔒 **Característica 2** — descripción breve
- 📊 **Característica 3** — descripción breve
## 🚀 Instalación rápida
```bash
git clone https://github.com/tu-usuario/tu-repo.git
cd tu-repo
npm install
cp .env.example .env
npm start
```
## 📖 Uso
```javascript
// Ejemplo de uso básico
const miProyecto = require('mi-proyecto');
miProyecto.iniciar({ config: 'valor' });
```
## ⚙️ Configuración
| Variable | Descripción | Por defecto |
|------------------|--------------------------------|--------------|
| `PORT` | Puerto del servidor | `3000` |
| `DATABASE_URL` | URL de conexión a la BD | Requerido |
| `JWT_SECRET` | Secreto para los tokens | Requerido |
## 🗺️ Roadmap
- [x] Funcionalidad A (v1.0)
- [x] Funcionalidad B (v1.0)
- [ ] Funcionalidad C (v1.1)
- [ ] Funcionalidad D (v2.0)
## 🤝 Contribuir
Lee [CONTRIBUTING.md](CONTRIBUTING.md) para los detalles.
## 📄 Licencia
[MIT](LICENSE) © [Tu Nombre](https://github.com/tu-usuario)
El README de perfil de GitHub — tu tarjeta de visita
GitHub tiene una función especial: si creas un repositorio con el mismo nombre que tu usuario (github.com/tu-usuario/tu-usuario) y le añades un README, ese README aparece en tu perfil público. Es tu carta de presentación para recruiters y la comunidad.
# Cómo activarlo:
# 1. Ve a GitHub → New Repository
# 2. Nombre del repo: TU-NOMBRE-DE-USUARIO (exactamente igual)
# 3. Márcalo como público
# 4. Inicialízalo con un README
# 5. El contenido del README aparecerá en tu perfil ✅
# Ejemplo de README de perfil:
# ¡Hola! Soy Ana García 👋
### 🚀 Desarrolladora Full Stack | Python • Node.js • React
Construyo APIs escalables y aplicaciones web desde Madrid 🇪🇸.
Apasionada por el código limpio, el open source y el café ☕.
---
### 🛠️ Stack principal
---
### 📌 Proyectos destacados
| Proyecto | Descripción | Stack |
|----------|-------------|-------|
| [StockAlert](https://github.com/ana/stockalert) | API de alertas de inventario | Node.js, PostgreSQL |
| [ML Dashboard](https://github.com/ana/ml-dashboard) | Dashboard para modelos de ML | Python, React |
| [DevNotes CLI](https://github.com/ana/devnotes) | Notas en la terminal | Python |
---
### 📊 Estadísticas de GitHub
---
### 📫 Contacto
[](https://linkedin.com/in/tu-perfil)
[](https://tu-portfolio.com)
[](mailto:tu@email.com)GitHub Stats — las tarjetas de estadísticas
# GitHub README Stats — el widget más popular para perfiles
# Repositorio: https://github.com/anuraghazra/github-readme-stats
# Estadísticas generales
# Lenguajes más usados
# Racha de contribuciones
# Temas disponibles: dark, radical, merko, gruvbox, tokyonight,
# onedark, cobalt, synthwave, highcontrast, dracula
# Sustituye TU_USUARIO por tu nombre de usuario de GitHubHerramientas para crear READMEs sin escribir Markdown
- 🛠️ readme.so (readme.so) — editor visual drag-and-drop con secciones predefinidas. El más recomendado para empezar
- 🛠️ shields.io (shields.io) — generador de badges con cientos de opciones y estilos
- 🛠️ GitHub Readme Stats — tarjetas de estadísticas para el perfil
- 🛠️ LICEcap — captura la pantalla como GIF animado (Windows/Mac)
- 🛠️ Carbon (carbon.now.sh) — genera capturas de código con diseño bonito para incluir en el README
- 🛠️ Markdown Preview en VS Code — previsualiza el README antes de subirlo (
Ctrl+Shift+V)
Los 7 errores más comunes en READMEs
❌ 1. El README vacío o con solo el título
# mi-proyecto
# Es mejor que no exista — al menos genera curiosidad negativa
# ✅ Dedica 20 minutos a escribir un README básico❌ 2. Instrucciones de instalación incompletas
# ❌ Asume conocimientos que el lector puede no tener npm start # ✅ Muestra cada paso desde cero git clone https://github.com/usuario/proyecto.git cd proyecto npm install cp .env.example .env # Edita .env con tus credenciales (ver sección Configuración) npm run dev # La app estará en http://localhost:3000
❌ 3. Sin capturas ni demos visuales
# ❌ Solo texto — el lector no sabe qué aspecto tiene
Este proyecto es una aplicación de gestión de tareas.
# ✅ Una imagen o GIF que muestre la funcionalidad principal
# Si no tienes GIF, al menos una captura de pantalla
❌ 4. Sobredosis de badges
# ❌ Demasiados badges — ruido visual, ninguno destaca
![badge1]() ![badge2]() ![badge3]() ![badge4]() ![badge5]()
![badge6]() ![badge7]() ![badge8]() ![badge9]() ![badge10]()
# ✅ 3-5 badges relevantes, en una línea limpia
[]() []() []()
[]() []()❌ 5. README desactualizado
# ❌ Instrucciones que ya no funcionan con la versión actual
npm install mi-proyecto@1.0
# Error: version 1.0 not found
# ✅ Mantén el README actualizado con cada release
# Añade una sección de CHANGELOG o versiona el README junto al código❌ 6. Sin licencia
# Sin licencia explícita, el código es técnicamente "todos los derechos reservados"
# nadie puede contribuir, forkear ni usar tu código legalmente
# ✅ Añade siempre una licencia
## 📄 Licencia
[MIT](LICENSE) — haz lo que quieras con el código
# Las licencias más comunes en open source:
# MIT → máxima libertad, mínimas restricciones (la más usada)
# Apache 2.0 → como MIT pero con protección de patentes
# GPL → el código derivado debe ser también open source❌ 7. Texto sin estructura — un muro de párrafos
# ❌ Texto continuo sin encabezados, listas ni código
Este proyecto es una API REST construida con Node.js y Express para gestionar
el inventario de una tienda. Para instalarlo necesitas tener Node.js instalado
y una base de datos PostgreSQL. Después clonas el repo, instalas con npm install,
configuras el .env y ejecutas npm start.
# ✅ Estructura clara con encabezados, listas y código
## Instalación
1. Clona el repositorio
2. Instala las dependencias con `npm install`
3. Configura las variables de entorno (ver sección Configuración)
4. Ejecuta con `npm start`Lista de verificación — el README ideal
README — Lista de verificación completa:
Estructura básica:
☐ Título descriptivo con emoji opcional
☐ Descripción de 1-2 frases: qué hace y para quién
☐ Badges relevantes (3-5 máximo)
☐ Demo visual: GIF, screenshot o enlace a demo en vivo
Contenido:
☐ Lista de características con valor diferencial
☐ Prerrequisitos claros (versiones exactas)
☐ Instrucciones de instalación paso a paso verificadas
☐ Ejemplo de uso básico con código real
☐ Tabla o sección de configuración (.env)
☐ Guía de contribución (aunque sea básica)
☐ Licencia especificada
Detalles profesionales:
☐ Tabla de contenidos (si el README es largo)
☐ Sección de API Reference (si es una librería/API)
☐ Roadmap o próximas funcionalidades
☐ Sección de FAQ con preguntas frecuentes
☐ Badges de CI/CD conectados al workflow real
☐ Links a documentación externa si la hayResumen: lo que aprendiste hoy
- ✅ El README es la portada de tu proyecto — determina si alguien lo usa o lo ignora
- ✅ GitHub usa GFM (GitHub Flavored Markdown) con características extra: tablas, listas de tareas, alertas
- ✅ La estructura ideal: título → badges → demo visual → características → instalación → uso → configuración → contribución → licencia
- ✅ Los badges de shields.io muestran información del proyecto en tiempo real — úsalos con moderación (3-5 máximo)
- ✅ Una imagen o GIF de demo vale más que cualquier descripción textual
- ✅ Las instrucciones de instalación deben ser verificadas y funcionar desde cero sin asumir nada
- ✅ El README de perfil personal aparece en tu página de GitHub — es tu tarjeta de visita para recruiters
- ✅ GitHub README Stats, shields.io, readme.so y Carbon son herramientas que elevan la calidad visual
- ✅ Siempre incluye una licencia — sin ella el código es legalmente inutilizable por terceros
- ✅ Mantén el README actualizado con cada versión del proyecto
🧪 ¿Tienes los fundamentos de Git y GitHub bien claros?
Un buen README es parte de trabajar bien con Git y GitHub. Para dominarlo todo necesitas tener claros los fundamentos: commits, ramas, pull requests y cómo colaborar en proyectos. Comprueba dónde estás:
👉 Test: Git y GitHub Básico 👉 Test: Fundamentos de Programación
¿Tenías el README de tus proyectos descuidado o ya lo cuidabas? ¿Cuál de las secciones que viste hoy te faltaba? ¿Ya tienes el README de perfil personal en GitHub? Cuéntanos en los comentarios 👇 — respondemos todos. 🚀
No hay comentarios todavía. Sé el primero en compartir tu opinión.