Guía Completa de Markdown
Markdown es un lenguaje de marcado ligero que puedes usar para añadir elementos de formato a documentos de texto plano. Creado por John Gruber en 2004, Markdown es ahora uno de los lenguajes de marcado más populares del mundo.
En esta guía aprenderás desde la sintaxis básica hasta técnicas avanzadas como la creación de diagramas profesionales que puedes usar en documentación técnica, presentaciones y proyectos.
Ejemplos de Diagramas que Aprenderás a Crear
Diagrama de Arquitectura de Sistema
Ideal para documentar arquitecturas full-stack y flujos de datos
Diagrama de Flujo de Aplicación React
Perfecto para visualizar el flujo de componentes y estados en aplicaciones
Diagrama de Secuencia
Excelente para documentar APIs y procesos de comunicación
Sintaxis Básica
Encabezados
# H1 - Encabezado Principal
## H2 - Encabezado de Sección
### H3 - Encabezado de Subsección
#### H4 - Encabezado de Nivel 4
##### H5 - Encabezado de Nivel 5
###### H6 - Encabezado de Nivel 6Resultado:
H2 - Encabezado de Sección
H3 - Encabezado de Subsección
Énfasis y Formato de Texto
*Texto en cursiva* o _Texto en cursiva_
**Texto en negrita** o __Texto en negrita__
***Texto en negrita y cursiva*** o ___Texto en negrita y cursiva___
~~Tachado~~
`Código en línea`
==Texto resaltado== (en algunos procesadores)Resultado:
- Texto en cursiva
- Texto en negrita
- Texto en negrita y cursiva
TachadoCódigo en línea
Listas
Listas No Ordenadas
- Primer elemento
- Segundo elemento
- Tercer elemento
- Elemento indentado
- Otro elemento indentado
- Elemento doblemente indentado
* También puedes usar asteriscos
+ O signos de sumaListas Ordenadas
1. Primer elemento
2. Segundo elemento
3. Tercer elemento
1. Elemento indentado
2. Otro elemento indentado
1. Elemento doblemente indentado
<!-- También funciona con números desordenados -->
1. Primer elemento
1. Segundo elemento (Markdown lo numerará correctamente)
1. Tercer elementoListas de Tareas
- [x] Tarea completada
- [ ] Tarea pendiente
- [x] ~~Tarea completada y tachada~~
- [ ] Tarea con **texto en negrita**
- [ ] Tarea con [enlace](https://ejemplo.com)Enlaces e Imágenes
<!-- Enlaces básicos -->
[Texto del enlace](https://www.ejemplo.com)
[Enlace con título](https://www.ejemplo.com "Título del enlace")
<!-- Enlaces de referencia -->
[Texto del enlace][1]
[1]: https://www.ejemplo.com "Título opcional"
<!-- Enlaces automáticos -->
<https://www.ejemplo.com>
<email@ejemplo.com>
<!-- Imágenes -->
<!-- Imagen con enlace -->
[](https://ejemplo.com)Código
Código en Línea
Usa `console.log()` para imprimir en la consola.
Puedes usar ``código con `backticks` dentro`` si necesitas backticks literales.Bloques de Código
```javascript
// Bloque de código JavaScript
const saludo = "¡Hola, mundo!";
console.log(saludo);
function sumar(a, b) {
return a + b;
}# Bloque de código Python
def saludar(nombre):
return f"¡Hola, {nombre}!"
print(saludar("Felipe"))/* Bloque de código CSS */
.ejemplo {
color: #333;
font-size: 16px;
margin: 10px 0;
}
### Citas
```markdown
> Esto es una cita simple.
> Esta es una cita multilínea.
> Puede abarcar varias líneas
> y mantener el formato.
> ## Citas con otros elementos
>
> - Pueden contener listas
> - Y otros elementos de Markdown
>
> **Texto en negrita** dentro de una cita.
> Citas anidadas
>> Esto es una cita dentro de otra cita
>>> Y esto es una cita de tercer nivelLíneas Horizontales
---
***
___
<!-- Todas crean el mismo efecto -->Sintaxis Extendida
Tablas
| Columna 1 | Columna 2 | Columna 3 |
|-----------|-----------|-----------|
| Dato 1 | Dato 2 | Dato 3 |
| Dato 4 | Dato 5 | Dato 6 |
<!-- Alineación -->
| Izquierda | Centro | Derecha |
|:----------|:------:|--------:|
| Texto | Texto | Texto |
| Más texto | Texto | Texto |
<!-- Tabla con formato -->
| Función | Descripción | Ejemplo |
|---------|-------------|---------|
| `console.log()` | Imprime en consola | `console.log("Hola")` |
| `alert()` | Muestra una alerta | `alert("Mensaje")` |
| `Math.random()` | Número aleatorio | `Math.random()` |Notas al Pie
Aquí hay una oración con una nota al pie[^1]. Y aquí hay otra[^nota-larga].
[^1]: Esta es la primera nota al pie.
[^nota-larga]: Esta es una nota al pie más larga que puede
abarcar varias líneas. Todas las líneas subsecuentes
deben estar indentadas.Definiciones
Término 1
: Definición 1
Término 2
: Definición 2a
: Definición 2b
Término con *formato*
: Las definiciones pueden contener **texto formateado**.Diagramas con Mermaid
Mermaid es una de las características más poderosas de Markdown moderno. Te permite crear diagramas profesionales directamente en tu documentación usando sintaxis de texto simple.
¿Por qué usar Mermaid?
- Versionado: Los diagramas se guardan como texto, perfectos para Git
- Mantenimiento: Fácil de actualizar y modificar
- Integración: Compatible con GitHub, GitLab, Notion y muchas plataformas
- Consistencia: Estilo profesional automático
Tipos de Diagramas Avanzados
1. Diagramas de Flujo
Los diagramas de flujo son ideales para documentar procesos, algoritmos y flujos de aplicaciones.
```mermaid
flowchart TD
A[Page.tsx] --> B[HydrationBoundary]
A --> C[Server Prefetch]
B --> D[Suspense]
D --> E[ErrorBoundary]
D --> F[Loading Fallback]
E --> G[View Component]
E --> H[Error Fallback]
F --> I[AgentsViewLoading]
G --> J[useSuspenseQuery]
H --> K[AgentsViewError]
I --> L[LoadingState]
J --> M[Cached Data]
K --> N[ErrorState]
L --> O[Loading Animation]
M --> P[Render Content]
O --> Q[Space Loader]
Q --> R[Astronaut Animation]
Q --> S[Space Environment]
Q --> T[Progress Bar]
C --> U[tRPC Router]
U --> V[Procedure Validation]
V --> W[Database Query]
W --> X[PostgreSQL]
style A fill:#4ade80
style N fill:#ef4444
style P fill:#4ade80
style Q fill:#f59e0b
**Casos de uso:**
- Documentación de arquitectura de aplicaciones React
- Flujos de manejo de errores y estados de carga
- Procesos de validación y autenticación
- Algoritmos y lógica de negocio
### 2. Diagramas de Secuencia
Perfectos para documentar APIs, procesos de comunicación y flujos temporales.
```markdown
```mermaid
sequenceDiagram
participant U as User
participant P as Page
participant S as Server
participant D as Database
participant C as Cache
Note over U,C: Initial Page Load
U->>P: Navigate to /agents
P->>S: Server-side prefetch
S->>D: Query agents data
D-->>S: Return data
S->>C: Populate cache
S-->>P: Hydrated state
P-->>U: Instant render
Note over U,C: No loading state needed
rect rgb(64, 64, 64)
Note over P,C: React Query cache & tRPC type safety
end
Note over U,C: User Navigation
U->>P: Navigate away & back
P->>C: Check cache
C-->>P: Return cached data
P-->>U: Instant render
Note over U,C: Background refetch if stale
rect rgb(64, 64, 64)
P->>S: Background refetch
S->>D: Query fresh data
D-->>S: Updated data
S-->>P: Update cache
end
**Casos de uso:**
- Documentación de APIs REST y GraphQL
- Flujos de autenticación OAuth
- Procesos de pago y transacciones
- Comunicación entre microservicios
### 3. Diagramas de Arquitectura
Ideales para mostrar la estructura completa de sistemas complejos.
```markdown
```mermaid
graph TB
subgraph "Client Side"
A[TypeScript Types] --> B[React Component]
B --> C[tRPC Client]
C --> D[React Query Hook]
D --> E[useSuspenseQuery]
end
subgraph "Network Layer"
F[HTTP Request] --> G[Next.js API Route]
G --> H[tRPC Handler]
end
subgraph "Server Side"
I[tRPC Router] --> J[Procedure Validation]
J --> K[Database Query]
K --> L[PostgreSQL]
M[Drizzle ORM] --> L
end
subgraph "Type Safety"
N[Shared Types] --> A
N --> O[Server Types]
N --> P[Database Schema]
end
E --> F
H --> I
style B fill:#61dafb
style I fill:#398ccb
style N fill:#f59e0b
style L fill:#336791
**Casos de uso:**
- Arquitecturas full-stack modernas
- Sistemas de microservicios
- Infraestructura cloud
- Flujos de datos complejos
### 4. Diagramas de Gantt
Perfectos para planificación de proyectos y cronogramas.
```mermaid
gantt
title Cronograma de Desarrollo del Proyecto
dateFormat YYYY-MM-DD
section Planificación
Análisis de Requisitos :a1, 2024-01-01, 30d
Diseño de Arquitectura :after a1, 20d
Prototipado :proto, after a1, 15d
section Desarrollo
Setup del Proyecto :setup, 2024-02-20, 5d
Backend API :backend, after setup, 40d
Frontend React :frontend, 2024-03-01, 35d
Integración :integration, after backend, 10d
section Testing
Unit Tests :unit, after frontend, 10d
Integration Tests :int-test, after integration, 5d
E2E Tests :e2e, after int-test, 10d
section Deployment
Staging Deploy :staging, after e2e, 3d
Production Deploy :prod, after staging, 2d```mermaid
gantt
title Cronograma de Desarrollo del Proyecto
dateFormat YYYY-MM-DD
section Planificación
Análisis de Requisitos :a1, 2024-01-01, 30d
Diseño de Arquitectura :after a1, 20d
Prototipado :proto, after a1, 15d
section Desarrollo
Setup del Proyecto :setup, 2024-02-20, 5d
Backend API :backend, after setup, 40d
Frontend React :frontend, 2024-03-01, 35d
Integración :integration, after backend, 10d
section Testing
Unit Tests :unit, after frontend, 10d
Integration Tests :int-test, after integration, 5d
E2E Tests :e2e, after int-test, 10d
section Deployment
Staging Deploy :staging, after e2e, 3d
Production Deploy :prod, after staging, 2d
### 5. Diagramas de Clases
Excelentes para documentar arquitecturas orientadas a objetos.
```mermaid
classDiagram
class Usuario {
+String id
+String nombre
+String email
+Date fechaRegistro
+Boolean activo
+login()
+logout()
+actualizarPerfil()
+cambiarPassword()
}
class Producto {
+String id
+String titulo
+Float precio
+String descripcion
+String categoria
+Integer stock
+Boolean disponible
+actualizarPrecio()
+actualizarStock()
+aplicarDescuento()
}
class Pedido {
+String id
+Date fecha
+String estado
+Float total
+String direccionEnvio
+procesarPago()
+confirmarPedido()
+cancelarPedido()
}
class DetallePedido {
+Integer cantidad
+Float precioUnitario
+Float subtotal
+calcularSubtotal()
}
Usuario "1" --> "0..*" Pedido : realiza
Pedido "1" --> "1..*" DetallePedido : contiene
DetallePedido "0..*" --> "1" Producto : incluye
Usuario "0..*" --> "0..*" Producto : favoritos6. Diagramas de Estados
Ideales para documentar máquinas de estado y flujos de vida.
stateDiagram-v2
[*] --> Borrador
Borrador --> EnRevision : enviar_revision
EnRevision --> Aprobado : aprobar
EnRevision --> Rechazado : rechazar
EnRevision --> Borrador : solicitar_cambios
Rechazado --> Borrador : editar
Aprobado --> Publicado : publicar
Publicado --> Archivado : archivar
Archivado --> Publicado : restaurar
Publicado --> [*] : eliminar
Archivado --> [*] : eliminar_definitivo
state EnRevision {
[*] --> PendienteRevision
PendienteRevision --> RevisandoContenido
RevisandoContenido --> RevisandoFormato
RevisandoFormato --> [*]
}7. Diagramas de Red
Perfectos para infraestructura y topologías de red.
graph TB
subgraph "Frontend"
A[React App] --> B[Nginx Reverse Proxy]
end
subgraph "Load Balancer"
B --> C[Load Balancer]
end
subgraph "Backend Services"
C --> D[API Server 1]
C --> E[API Server 2]
C --> F[API Server 3]
end
subgraph "Database Layer"
D --> G[Primary Database]
E --> G
F --> G
G --> H[Read Replica 1]
G --> I[Read Replica 2]
end
subgraph "Cache Layer"
D --> J[Redis Cache]
E --> J
F --> J
end
subgraph "External Services"
D --> K[Payment Gateway]
E --> L[Email Service]
F --> M[File Storage]
endConsejos para Diagramas Efectivos
1. Planificación
<!-- Antes de crear el diagrama, define: -->
- ¿Cuál es el propósito del diagrama?
- ¿Quién es la audiencia?
- ¿Qué nivel de detalle necesitas?
- ¿Qué tipo de diagrama es más apropiado?2. Estilo y Consistencia
```mermaid
flowchart TD
A[Inicio] --> B{Decisión}
B -->|Sí| C[Acción Positiva]
B -->|No| D[Acción Negativa]
%% Aplicar estilos consistentes
style A fill:#4ade80,stroke:#22c55e,stroke-width:2px
style C fill:#4ade80,stroke:#22c55e,stroke-width:2px
style D fill:#ef4444,stroke:#dc2626,stroke-width:2px
style B fill:#f59e0b,stroke:#d97706,stroke-width:2px
### 3. Documentación de Diagramas
```markdown
<!-- Siempre incluye contexto -->
## Diagrama de Flujo de Autenticación
Este diagrama muestra el proceso completo de autenticación de usuarios,
incluyendo el manejo de errores y la validación de tokens.
```mermaid
<!-- Tu diagrama aquí -->Notas importantes:
- Los tokens expiran después de 24 horas
- Se requiere verificación 2FA para operaciones sensibles
- Los errores se registran en el sistema de logs
## Fórmulas Matemáticas
### LaTeX/MathJax
```markdown
<!-- Fórmulas en línea -->
La fórmula de Einstein es $E = mc^2$.
<!-- Fórmulas en bloque -->
$$\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n$$
<!-- Fórmulas complejas -->
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
<!-- Matrices -->
$$\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}$$
<!-- Sistemas de ecuaciones -->
$$\begin{cases}
x + y = 5 \\
2x - y = 1
\end{cases}$$Elementos HTML en Markdown
<!-- Puedes usar HTML directamente -->
<div style="color: red;">Texto rojo</div>
<details>
<summary>Haz clic para expandir</summary>
Contenido colapsable que se muestra al hacer clic.
</details>
<kbd>Ctrl</kbd> + <kbd>C</kbd> para copiar
<mark>Texto resaltado</mark>
<sub>subíndice</sub> y <sup>superíndice</sup>
<!-- Comentarios HTML (no se muestran) -->
<!-- Este es un comentario -->Elementos Avanzados
Alertas y Admoniciones
> [!NOTE]
> Información útil que los usuarios deben conocer.
> [!TIP]
> Consejo opcional que puede ser útil.
> [!IMPORTANT]
> Información crucial que los usuarios necesitan saber.
> [!WARNING]
> Contenido crítico que necesita atención inmediata.
> [!CAUTION]
> Consecuencias negativas de una acción.Escape de Caracteres
<!-- Para mostrar caracteres especiales literalmente -->
\* No es una lista
\# No es un encabezado
\[No es un enlace\]
\`No es código\`
<!-- Caracteres que necesitan escape -->
\ ` * _ { } [ ] ( ) # + - . !Mejores Prácticas
1. Estructura y Organización
- Usa encabezados jerárquicamente: Comienza con H1 y usa niveles inferiores para subsecciones
- Añade una tabla de contenidos para documentos largos
- Usa líneas en blanco para separar secciones y mejorar la legibilidad
2. Formato Consistente
- Mantén un estilo uniforme para elementos similares
- Usa el mismo marcador para listas no ordenadas (-, *, o +)
- Indenta con espacios en lugar de tabs para mejor compatibilidad
3. Enlaces e Imágenes
- Usa texto descriptivo para los enlaces
- Añade texto alternativo a todas las imágenes
- Verifica que los enlaces funcionen antes de publicar
4. Código y Ejemplos
- Especifica el lenguaje en los bloques de código para resaltado de sintaxis
- Usa código en línea para comandos y nombres de variables
- Incluye ejemplos prácticos para conceptos complejos
5. Diagramas Profesionales
- Planifica antes de crear: Define el propósito y audiencia
- Mantén la simplicidad: No sobrecargues con detalles innecesarios
- Usa colores consistentes: Aplica un esquema de colores coherente
- Documenta el contexto: Explica qué muestra cada diagrama
6. Accesibilidad
- Usa encabezados descriptivos que tengan sentido fuera de contexto
- Proporciona contexto para enlaces y referencias
- Evita usar solo color para transmitir información
Errores Comunes y Soluciones
1. Problemas de Formato
<!-- ❌ Incorrecto -->
#Sin espacio después del hash
- [x]Sin espacio después de los corchetes
<!-- ✅ Correcto -->
# Con espacio después del hash
- [x] Con espacio después de los corchetes2. Listas Anidadas
<!-- ❌ Incorrecto -->
- Elemento 1
- Elemento 2
- Elemento anidado (no está bien indentado)
<!-- ✅ Correcto -->
- Elemento 1
- Elemento 2
- Elemento anidado (indentado con 2 espacios)3. Diagramas Mermaid
<!-- ❌ Incorrecto -->
```mermaid
flowchart TD
A-->B
B-->Cflowchart TD
A[Inicio] --> B[Proceso]
B --> C[Fin]
### 4. Enlaces Rotos
```markdown
<!-- ❌ Evitar -->
[enlace roto](url-que-no-existe.com)
<!-- ✅ Verificar siempre -->
[enlace funcionando](https://ejemplo.com)Herramientas y Recursos
Editores de Markdown
- Typora - Editor WYSIWYG para Markdown
- Mark Text - Editor gratuito y de código abierto
- Obsidian - Para tomar notas con Markdown
- VS Code con extensiones de Markdown
Conversores y Procesadores
- Pandoc - Conversor universal de documentos
- markdown-it - Parser de Markdown para JavaScript
- marked - Parser y compilador de Markdown
Herramientas Online
- Dillinger - Editor online con vista previa
- StackEdit - Editor completo en el navegador
- Markdown Live Preview - Vista previa rápida
- Mermaid Live Editor - Para crear diagramas
Herramientas para Diagramas
- Mermaid Live Editor - Editor online para diagramas Mermaid
- Draw.io - Crear diagramas que luego puedes exportar
- Excalidraw - Diagramas de aspecto dibujado a mano
- PlantUML - Alternativa a Mermaid para diagramas
Referencias y Documentación
- CommonMark Spec - Especificación estándar
- GitHub Flavored Markdown - Extensiones de GitHub
- Markdown Guide - Guía completa
- Mermaid Documentation - Para diagramas
Casos de Uso Comunes
Documentación Técnica
# API Documentation
## Endpoint: `/api/users`
### GET /api/users
Retrieves a list of users.
**Parameters:**
- `limit` (integer, optional): Maximum number of users to return
- `offset` (integer, optional): Number of users to skip
**Response:**
```json
{
"users": [...],
"total": 100,
"limit": 10,
"offset": 0
}Status Codes:
200: Success400: Bad Request500: Internal Server Error
Flow Diagram:
sequenceDiagram
participant C as Client
participant A as API
participant D as Database
C->>A: GET /api/users
A->>D: SELECT users
D-->>A: User data
A-->>C: JSON response
### README de Proyecto
```markdown
# Mi Proyecto Increíble
## Descripción
Una breve descripción de lo que hace tu proyecto.
## Arquitectura
```mermaid
graph TB
A[Frontend React] --> B[API Gateway]
B --> C[Microservicio 1]
B --> D[Microservicio 2]
C --> E[Database]
D --> EInstalación
npm install mi-proyectoUso
import { MiClase } from 'mi-proyecto';
const instancia = new MiClase();
instancia.metodo();Contribuir
- Fork el proyecto
- Crea una rama para tu feature
- Commit tus cambios
- Push a la rama
- Abre un Pull Request
## Conclusión
Markdown es una herramienta versátil y poderosa que va mucho más allá del formato básico de texto. Con diagramas profesionales, fórmulas matemáticas, tablas avanzadas y elementos HTML, puedes crear documentación rica y profesional que realmente destaque.
### Los diagramas que has visto en esta guía demuestran que Markdown puede:
- **Documentar arquitecturas complejas** de manera visual y clara
- **Mostrar flujos de datos** y procesos de manera profesional
- **Explicar secuencias temporales** con precisión
- **Mantener documentación actualizada** fácilmente
### La clave del éxito con Markdown está en:
- **Practicar regularmente** para familiarizarte con la sintaxis
- **Usar las herramientas adecuadas** para tu flujo de trabajo
- **Mantener la consistencia** en tu formato
- **Aprovechar los diagramas** para comunicar ideas complejas
- **Documentar el contexto** de tus diagramas y código
Ya sea que estés escribiendo documentación técnica, creando contenido para blogs, documentando APIs, o explicando arquitecturas de software, Markdown con Mermaid te proporciona todas las herramientas necesarias para crear contenido profesional, mantenible y visualmente atractivo.
¡Empieza a experimentar con estos elementos y verás cómo Markdown puede transformar completamente tu forma de escribir, documentar y comunicar ideas técnicas!