Una guía de referencia completa de la sintaxis Markdown, con mejores prácticas para READMEs, descripciones de pull requests y documentación técnica.
Todo developer escribe documentación. READMEs, descripciones de pull requests, tickets de Jira, wikis internas, páginas de Notion: todas usan Markdown. Pero la mayoría aprende solo la sintaxis básica para salir del paso y nunca descubre las funcionalidades que hacen que su documentación destaque.
Esta guía cubre todo, desde los conceptos básicos hasta los patrones profesionales que hacen que la documentación sea fácil de leer, fácil de mantener y fácil de encontrar.
Markdown es el lenguaje universal de la documentación para developers. GitHub, GitLab, Bitbucket, Notion, Linear, Confluence, Jira y Slack todos renderizan Markdown. Cuando escribes documentación clara y bien estructurada, tus compañeros pueden entender tu trabajo sin pedirte que lo expliques. Esa visibilidad se acumula con el tiempo: un developer que escribe buena documentación se destaca de maneras que un developer que solo escribe buen código no logra.
Markdown tiene dos ventajas clave sobre otros formatos. Primero, es texto plano, por lo que funciona en cualquier editor, viaja a través del control de versiones sin conflictos binarios y se renderiza en cualquier visor de Markdown. Segundo, la sintaxis es lo suficientemente mínima para leer sin renderizar: un archivo lleno de # y ** sigue siendo legible.
Los headers crean la estructura y jerarquía de un documento. Funcionan exactamente como los encabezados que ves en cualquier página web: el navegador (o el renderizador de Markdown) los muestra más grandes y en negrita que el texto normal, y cada nivel es más pequeño que el anterior.
El número de símbolos # define el nivel: un solo # da el encabezado más grande (H1), seis ###### dan el más pequeño (H6). Cada # adicional baja un nivel en la jerarquía.
En la práctica, la mayoría de los READMEs solo usan H1 hasta H3. H1 es el nombre del proyecto y solo debería haber uno por documento. H2 divide el documento en secciones principales como Instalación, Uso y Contribuir. H3 divide esas secciones en subsecciones. H4 a H6 existen pero rara vez se necesitan: si te encuentras usando H5, el documento probablemente necesita reestructurarse en lugar de más niveles de anidación.
Negrita e itálica son las dos herramientas de formato que más usarás. El tachado es útil en listas de tareas y changelogs.
| Format | Syntax | Result |
|---|---|---|
| Negrita | **negrita** | negrita |
| Itálica | *itálica* | itálica |
| Negrita + itálica | ***negrita e itálica*** | negrita e itálica |
| Tachado | ~~tachado~~ |
Separa los párrafos con una línea en blanco. Un solo salto de línea dentro de un párrafo se ignora. Para forzar un salto de línea dentro de un párrafo, termina la línea con dos espacios o una barra invertida (\).
La sintaxis del link es [texto](url). El texto entre corchetes es lo que el lector ve y puede hacer clic: puede ser cualquier cosa, completamente independiente de la URL. También puedes agregar un tooltip que aparece al pasar el cursor poniendo un título entre comillas después de la URL: [texto](url "Texto del tooltip").
Las imágenes usan la misma sintaxis que los links pero con un ! al principio. El texto entre corchetes es el texto alternativo, que se muestra cuando la imagen no se puede cargar y es leído por los lectores de pantalla.
Usa -, * o + como marcadores de viñeta. El marcador debe ir seguido de un espacio.
Usa números seguidos de un punto. Cada elemento tiene su propio número.
Indenta con dos o cuatro espacios para crear elementos anidados.
Las listas de tareas son una de las funcionalidades más útiles de GitHub Flavored Markdown. Se renderizan como checkboxes interactivos en issues, pull requests y descripciones de proyectos de GitHub.
Rodea el código con backticks simples para formato en línea. Úsalo para nombres de variables, rutas de archivos, comandos y fragmentos cortos.
Usa triple backtick para crear un bloque de código. Agrega el nombre del lenguaje después de los backticks iniciales para activar el resaltado de sintaxis. Esta es una de las mejoras más visibles que puedes hacer en tu documentación.
Los lenguajes soportados incluyen: python, javascript, typescript, bash, sql, json, yaml, go, rust, java y muchos más.
Usa diff como lenguaje para mostrar adiciones y eliminaciones. Prefija las líneas con + para adiciones y - para eliminaciones.
Los bloques diff son más útiles en descripciones de pull requests y changelogs. Cuanto más claros sean tus commits, más contexto aportan los diffs. Guía de Git Commit Messages.
Las tablas usan el carácter pipe (|) como separador de columnas. La segunda fila contiene los marcadores de alineación: --- para izquierda (por defecto), :---: para centro, ---: para derecha.
No es necesario alinear los pipes manualmente. Los renderizadores de Markdown ignoran los espacios adicionales.
Usa > para crear una cita. Las citas son útiles para notas, advertencias, avisos y para citar otros documentos.
GitHub soporta citas de alerta con estilo usando [!NOTE], [!WARNING], [!TIP], [!IMPORTANT] y [!CAUTION] dentro de la cita.
GitHub Flavored Markdown (GFM) extiende el Markdown estándar con funcionalidades especialmente útiles para los flujos de trabajo de desarrollo.
En GitHub, ciertas referencias se enlazan automáticamente sin ninguna sintaxis Markdown. Esto hace que las descripciones de pull requests y los comentarios de issues sean mucho más fáciles de escanear.
| Syntax | Result |
|---|---|
#123 | Enlaza al issue o PR #123 |
user/repo#123 | Enlaza al issue o PR en otro repositorio |
@username | Menciona a un usuario |
Hash SHA1 (7+ caracteres) | Enlaza a un commit |
Estas referencias son más útiles en descripciones de pull requests y comentarios de code review. guía de comentarios de code review.
Usa el elemento HTML <details> para crear secciones colapsables. Esto es útil para outputs largos, stack traces o ejemplos de configuración que saturarían el texto principal.
Las notas al pie son útiles para agregar referencias o aclaraciones sin saturar el texto principal.
Los badges son la forma más rápida de comunicar el estado del proyecto de un vistazo. Explora todos los badges disponibles en shields.io/badges.
Un README es la puerta de entrada de tu proyecto. Cuando alguien llega a tu repositorio, pasa unos 30 segundos escaneando el README antes de decidir si leer más. Aquí está la estructura que hace que esos 30 segundos valgan la pena.
Una vez que dominás el README, los mismos principios aplican a documentos técnicos más extensos. Cómo escribir un design doc en inglés.
| Syntax | Result |
|---|---|
# H1 / ## H2 / ### H3 | Headers |
**texto** | Negrita |
*texto* | Itálica |
~~texto~~ | Tachado |
[texto](url) | Link |
 | Imagen |
- elemento | Elemento de lista sin orden |
1. elemento | Elemento de lista ordenada |
- [x] tarea | Tarea completada |
- [ ] tarea | Tarea pendiente |
`código` | Código en línea |
```lang\ncódigo\n``` | Bloque de código con resaltado |
> texto | Cita |
| col | col | | Fila de tabla |
--- | Separador horizontal |
GitHub renderiza diagramas Mermaid de forma nativa dentro de bloques de código Markdown. Eso significa que podés agregar diagramas de flujo, diagramas de secuencia y diagramas de estado a tu README con solo código, sin exportar imágenes ni usar herramientas externas. Estos son cuatro ejemplos de un proyecto real:
El curso completo cubre exactamente cómo agregar diagramas como estos a tus READMEs, incluyendo la sintaxis, los tipos de diagramas y cómo hacer que se vean bien.

Escrito por
Roxana LafuenteFundadora de Lingua-e
Roxana Lafuente es ingeniera de software con más de 8 años de experiencia. Al comienzo de su carrera, aunque ya había aprobado el First Certificate in English, se bloqueaba cada vez que tenía que hablar en el standup diario. Era un problema que nadie estaba resolviendo. Después de más de 2.000 standups, descubrió qué es lo que realmente construye la fluidez: practicar situaciones que se parecen a tu trabajo real. Creó Lingua-e para que otros developers no tuvieran que tomar el camino largo para sentirse seguros trabajando en un entorno de desarrollo internacional.
Para mejorar tu experiencia y analizar el uso del sitio. Política de privacidad