Lingua-e
Tutorial de Markdown

Documentación en Markdown que te hace destacar como developer

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.

En esta guía
  1. Por qué importa Markdown
  2. Sintaxis básica
  3. Links e imágenes
  4. Listas
  5. Código
  6. Tablas
  7. Citas
  8. GitHub Flavored Markdown
  9. Mejores prácticas para READMEs
  10. Referencia rápida

Por qué Markdown importa para los developers

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.

Sintaxis básica

Headers

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.

Syntax
# H1 — Título del proyecto
## H2 — Sección principal
### H3 — Subsección
#### H4 — Sub-subsección
##### H5 — Encabezado menor
###### H6 — Encabezado más pequeño
Rendered

H1 — Título del proyecto

H2 — Sección principal

H3 — Subsección

H4 — Sub-subsección

H5 — Encabezado menor
H6 — Encabezado más pequeño

Formato de texto

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.

FormatSyntaxResult
Negrita**negrita**negrita
Itálica*itálica*itálica
Negrita + itálica***negrita e itálica***negrita e itálica
Tachado~~tachado~~tachado

Párrafos y saltos de línea

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 (\).

Links

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").

Syntax
Visita [Lingua-e](https://www.lingua-e.com) para practicar.
Rendered

Visita Lingua-e para practicar.

Imágenes

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.

Syntax
![Keystroke progression graph](https://github.com/roxana-lafuente/ResearchAnalyzer/raw/master/images/keystroke_progression_graph.png)
Rendered

Keystroke progression graph

Listas

Listas sin orden

Usa -, * o + como marcadores de viñeta. El marcador debe ir seguido de un espacio.

Syntax
- Node.js 18+
- PostgreSQL 14+
- Docker (opcional)
Rendered
  • Node.js 18+
  • PostgreSQL 14+
  • Docker (opcional)

Listas ordenadas

Usa números seguidos de un punto. Cada elemento tiene su propio número.

Syntax
1. Clona el repositorio
2. Instala las dependencias
3. Copia el archivo env
4. Inicia la base de datos
5. Ejecuta el servidor
Rendered
  1. Clona el repositorio
  2. Instala las dependencias
  3. Copia el archivo env
  4. Inicia la base de datos
  5. Ejecuta el servidor

Listas anidadas

Indenta con dos o cuatro espacios para crear elementos anidados.

Syntax
- Backend
  - FastAPI
  - PostgreSQL
- Frontend
  - Next.js
  - Tailwind CSS
Rendered
  • Backend
    • FastAPI
    • PostgreSQL
  • Frontend
    • Next.js
    • Tailwind CSS

Listas de tareas (GitHub Flavored Markdown)

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.

Syntax
- [x] Agregar autenticación
- [x] Configurar la base de datos
- [ ] Escribir tests
- [ ] Deploy a staging
Rendered
  • Agregar autenticación
  • Configurar la base de datos
  • Escribir tests
  • Deploy a staging

Código

Código en línea

Rodea el código con backticks simples para formato en línea. Úsalo para nombres de variables, rutas de archivos, comandos y fragmentos cortos.

Syntax
Ejecuta `npm install` antes de iniciar el servidor. La configuración está en `src/config.ts`.
Rendered

Ejecuta npm install antes de iniciar el servidor. La configuración está en src/config.ts.

Bloques de código

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.

Syntax
```python
def saludar(nombre: str) -> str:
    return f"Hola, {nombre}!"

print(saludar("mundo"))
```
Rendered
def saludar(nombre: str) -> str:
    return f"Hola, {nombre}!"

print(saludar("mundo"))

Los lenguajes soportados incluyen: python, javascript, typescript, bash, sql, json, yaml, go, rust, java y muchos más.

Bloques diff

Usa diff como lenguaje para mostrar adiciones y eliminaciones. Prefija las líneas con + para adiciones y - para eliminaciones.

Syntax
```diff
- return user.name
+ return user.display_name or user.name
```
Rendered
- return user.name
+ return user.display_name or user.name

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.

¿Querés ver la sintaxis aplicada a proyectos reales? El curso completo recorre READMEs de producción de principio a fin.Ir al curso →

Tablas

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.

Syntax
| Comando | Descripción |
|---------|-------------|
| `npm install` | Instalar dependencias |
| `npm run dev` | Iniciar servidor de desarrollo |
| `npm test` | Ejecutar tests |
| `npm run build` | Compilar para producción |
Rendered
ComandoDescripción
npm installInstalar dependencias
npm run devIniciar servidor de desarrollo
npm testEjecutar tests
npm run buildCompilar para producción

No es necesario alinear los pipes manualmente. Los renderizadores de Markdown ignoran los espacios adicionales.

Citas

Usa > para crear una cita. Las citas son útiles para notas, advertencias, avisos y para citar otros documentos.

Syntax
> **Nota**
> Esta funcionalidad requiere Node.js 18 o posterior.

> **Advertencia**
> Ejecutar este comando en producción eliminará todos los datos.
Rendered

Nota Esta funcionalidad requiere Node.js 18 o posterior.

Advertencia Ejecutar este comando en producción eliminará todos los datos.

GitHub soporta citas de alerta con estilo usando [!NOTE], [!WARNING], [!TIP], [!IMPORTANT] y [!CAUTION] dentro de la cita.

Syntax
> [!WARNING]
> Ejecutar este comando en producción eliminará todos los datos.
Rendered

[!WARNING] Ejecutar este comando en producción eliminará todos los datos.

GitHub Flavored Markdown

GitHub Flavored Markdown (GFM) extiende el Markdown estándar con funcionalidades especialmente útiles para los flujos de trabajo de desarrollo.

Referencias con autolink

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.

SyntaxResult
#123Enlaza al issue o PR #123
user/repo#123Enlaza al issue o PR en otro repositorio
@usernameMenciona 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.

Secciones colapsables

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.

Syntax
<details>
<summary>Stack trace completo</summary>

```
Error: Cannot read properties of undefined
    at getUserName (index.js:12)
    at main (index.js:34)
```

</details>
Rendered
Stack trace completo
Error: Cannot read properties of undefined
    at getUserName (index.js:12)
    at main (index.js:34)

Notas al pie

Las notas al pie son útiles para agregar referencias o aclaraciones sin saturar el texto principal.

Syntax
Esta funcionalidad es experimental.[^1]

[^1]: Las funcionalidades experimentales pueden cambiar en versiones futuras.
Rendered

Esta funcionalidad es experimental.1

Footnotes

  1. Las funcionalidades experimentales pueden cambiar en versiones futuras. ↩

Estas funcionalidades de GFM se cubren en profundidad con ejemplos de repositorios reales en el curso completo.Ir al curso →

Badges

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.

Syntax
![Cobertura](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)

![Versión](https://img.shields.io/npm/v/tu-paquete)

![Licencia](https://img.shields.io/badge/license-MIT-blue)
Rendered

Cobertura

Versión

Licencia

Mejores prácticas para READMEs

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.

Estructura que todo README debería tener

1
Título y descripción en una línea
El nombre del proyecto como H1, luego una oración explicando qué hace y para quién es.
2
Badges
Estado del build, cobertura de tests, versión, licencia. Ponlos justo después del título para dar credibilidad inmediata.
3
Instalación
Comandos listos para copiar y pegar. No asumas nada sobre la configuración del lector. Especifica los requisitos de versión exactos.
4
Uso
Un ejemplo de código mostrando el caso más común. Agrega más ejemplos para diferentes escenarios.
5
Configuración
Una tabla de variables de entorno u opciones de configuración con sus valores por defecto y descripciones.
6
Contribuir
Cómo abrir issues, ejecutar tests y enviar pull requests. Enlaza a un CONTRIBUTING.md si se hace largo.
7
Licencia
Una línea nombrando la licencia y enlazando al archivo LICENSE.

Tres reglas para documentación legible

Documenta el por qué, no solo el qué
El código ya muestra qué hace. La documentación explica por qué se tomó una decisión: 'Usamos polling en vez de webhooks porque la API de terceros no soporta webhooks.'
Que sea fácil de escanear
Usa headers, viñetas y párrafos cortos. La mayoría de los lectores escanea antes de leer. Si tu documentación es un bloque de texto, no se leerá.
Actualízala cuando cambie el código
La documentación desactualizada es peor que ninguna documentación: hace perder tiempo. Agrega un paso a tu definición de hecho: actualizar el README cuando cambie el comportamiento.

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.

El curso completo muestra cómo construir esta estructura desde cero para distintos tipos de proyectos.Ir al curso →

Referencia rápida

SyntaxResult
# H1 / ## H2 / ### H3Headers
**texto**Negrita
*texto*Itálica
~~texto~~Tachado
[texto](url)Link
![alt](url)Imagen
- elementoElemento de lista sin orden
1. elementoElemento de lista ordenada
- [x] tareaTarea completada
- [ ] tareaTarea pendiente
`código`Código en línea
```lang\ncódigo\n```Bloque de código con resaltado
> textoCita
| col | col |Fila de tabla
---Separador horizontal

Una cosa más: diagramas Mermaid

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:

Diagrama de flujo
Diagrama de flujo
Diagrama de secuencia
Diagrama de secuencia
Diagrama de estados
Diagrama de estados
Diagrama de estados (tema oscuro)
Diagrama de estados (tema oscuro)

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.

Markdown Documentation That Gets You Noticed as a Developer — Udemy course
Lleva tu documentación al siguiente nivel

Markdown Documentation That Gets You Noticed as a Developer

Ve más allá de la sintaxis y aprende a estructurar documentación que realmente se lee: READMEs que hacen que tus proyectos destaquen, changelogs que comunican con claridad y hábitos de escritura que te convierten en el developer en quien los equipos confían para la documentación.

5,0 ★por Roxana Lafuente
Ver en Udemy →
Roxana Lafuente

Escrito por

Roxana Lafuente

Fundadora 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.

← Tutoriales