Guía Completa de Markdown: Sintaxis, Consejos y Mejores Prácticas

· 12 min de lectura

Tabla de Contenidos

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero creado por John Gruber en colaboración con Aaron Swartz en 2004. Te permite escribir texto formateado usando sintaxis de texto plano que permanece legible incluso sin renderizar. En lugar de hacer clic en botones en un procesador de texto o escribir etiquetas HTML verbosas, usas caracteres simples e intuitivos como # para encabezados, ** para texto en negrita y - para listas.

La filosofía detrás de Markdown es elegantemente simple: el texto fuente debe ser tan legible como la salida renderizada. Cuando abres un archivo Markdown en cualquier editor de texto, puedes entender inmediatamente su estructura y contenido sin necesitar software especial o motores de renderizado.

Markdown se ha convertido en el estándar de facto para escritura técnica, documentación, archivos README, publicaciones de blog y toma de notas en todo el mundo del desarrollo de software. Plataformas importantes como GitHub, GitLab, Reddit, Stack Overflow, Discord, Slack, Notion y Obsidian soportan Markdown de forma nativa, convirtiéndolo en una habilidad esencial para desarrolladores, escritores técnicos y creadores de contenido.

¿Por qué usar Markdown?

Consejo profesional: Si trabajas regularmente con archivos Markdown, prueba nuestro Editor de Markdown para vista previa en vivo y resaltado de sintaxis, o usa el Convertidor de Markdown a HTML para transformar tus documentos instantáneamente.

Encabezados y Estructura del Documento

Los encabezados son la columna vertebral de la estructura del documento en Markdown. Usan el símbolo #, donde el número de símbolos de almohadilla determina el nivel del encabezado del 1 al 6:

# Encabezado 1
## Encabezado 2
### Encabezado 3
#### Encabezado 4
##### Encabezado 5
###### Encabezado 6

Siempre incluye un espacio después del símbolo #—la mayoría de los procesadores de Markdown lo requieren, y mejora la legibilidad. La salida renderizada crea etiquetas de encabezado HTML apropiadas (<h1> hasta <h6>), que son cruciales para la estructura del documento, accesibilidad y SEO.

Mejores Prácticas para Encabezados

Usa niveles de encabezado secuencialmente sin saltar niveles. No saltes de H1 a H3—esto rompe la jerarquía del documento y crea problemas de accesibilidad para usuarios de lectores de pantalla. Piensa en los encabezados como un esquema: cada nivel debe anidarse lógicamente dentro del anterior.

La mayoría de los documentos deben tener solo un encabezado H1 (el título), con encabezados H2 para secciones principales y H3-H6 para subsecciones. Esto crea una jerarquía de información clara que tanto humanos como motores de búsqueda pueden entender.

Consejo rápido: Muchos procesadores de Markdown generan automáticamente enlaces de anclaje para encabezados, permitiéndote enlazar directamente a secciones específicas. GitHub, por ejemplo, convierte "## Comenzando" en un anclaje que puedes referenciar con #comenzando.

Sintaxis Alternativa de Encabezados

Markdown también soporta una sintaxis alternativa para encabezados H1 y H2 usando subrayados:

Encabezado 1
============

Encabezado 2
------------

Aunque esta sintaxis es válida, la sintaxis de almohadilla es más común y soporta los seis niveles de encabezado, haciéndola la opción preferida para la mayoría de los escritores.

Fundamentos de Formato de Texto

Markdown proporciona sintaxis simple e intuitiva para necesidades comunes de formato de texto. Estas opciones de formato funcionan en línea dentro de párrafos y pueden combinarse para estilos más complejos.

Formato Sintaxis Alternativa Resultado
Negrita **negrita** __negrita__ negrita
Cursiva *cursiva* _cursiva_ cursiva
Negrita + Cursiva ***ambas*** ___ambas___ ambas
Tachado ~~eliminado~~ — eliminado
Código en línea `código` — código
Subíndice H~2~O — H2O
Superíndice X^2^ — X2
Resaltado ==marcado== — marcado

Detalles de Sintaxis de Énfasis

Tanto los asteriscos (*) como los guiones bajos (_) funcionan para énfasis, pero los asteriscos son más comúnmente usados y recomendados. La diferencia clave: los asteriscos funcionan a mitad de palabra (in*creí*ble), mientras que los guiones bajos requieren límites de palabra.

Para texto en negrita, usa asteriscos o guiones bajos dobles. Para texto en cursiva, usa asteriscos o guiones bajos simples. Combina tres para texto en negrita y cursiva. Esta consistencia hace que tu fuente Markdown sea más legible y predecible.

Consejo profesional: Al escribir documentación técnica, usa `comillas invertidas` para código en línea, nombres de funciones, rutas de archivos y argumentos de línea de comandos. Esta distinción visual ayuda a los lectores a identificar rápidamente elementos de código dentro de la prosa.

Escapar Caracteres Especiales

Si necesitas mostrar asteriscos literales, guiones bajos u otros caracteres de sintaxis de Markdown, escápalos con una barra invertida:

Esto \*no es cursiva\* y \*\*no es negrita\*\*
Usa \# para mostrar un símbolo de almohadilla sin crear un encabezado

Los caracteres comunes que necesitan escape incluyen: \ ` * _ { } [ ] ( ) # + - . !

Listas: Ordenadas, Desordenadas y Anidadas

Las listas son fundamentales para organizar información en Markdown. Son simples de crear y soportan anidamiento para contenido jerárquico.

Listas Desordenadas

Crea listas desordenadas (con viñetas) usando -, * o + seguido de un espacio. Los tres marcadores funcionan idénticamente, pero la consistencia dentro de un documento mejora la legibilidad:

- Primer elemento
- Segundo elemento
- Tercer elemento
  - Elemento anidado (sangría con 2 espacios)
  - Otro elemento anidado
- Cuarto elemento

La sangría estándar para listas anidadas es de dos espacios, aunque algunos analizadores aceptan cuatro. Mantente con dos espacios para máxima compatibilidad.

Listas Ordenadas

Las listas ordenadas (numeradas) usan números seguidos de puntos y un espacio:

1. Primer paso
2. Segundo paso
3. Tercer paso
   1. Sub-paso A
   2. Sub-paso B
4. Cuarto paso

Aquí hay una característica útil: los números reales que uses no importan. Markdown renumera automáticamente las listas secuencialmente cuando se renderizan. Puedes usar 1. para cada elemento, facilitando reordenar elementos sin renumerar:

1. Primer elemento
1. Segundo elemento
1. Tercer elemento

Esto se renderiza como una lista numerada apropiadamente 1, 2, 3. Esta técnica es particularmente útil al mantener listas largas o reordenar elementos frecuentemente.

Listas de Tareas

Muchos sabores de Markdown (incluyendo GitHub Flavored Markdown) soportan listas de tareas con casillas de verificación:

- [x] Tarea completada
- [ ] Tarea incompleta
- [ ] Otra tarea incompleta

Las listas de tareas son invaluables para gestión de proyectos, seguimiento de problemas y listas de tareas pendientes en documentación.

Consejo rápido: Para incluir múltiples párrafos o bloques de código dentro de un elemento de lista, sangra el contenido subsecuente para alinearlo con el primer carácter del texto del elemento de lista (típicamente 3-4 espacios para listas desordenadas, 4 espacios para listas ordenadas).

Listas de Definiciones

Algunas sintaxis extendidas de Markdown soportan listas de definiciones para glosarios y definiciones de términos:

Término 1
: Definición para término 1

Término 2
: Primera definición para término 2
: Segunda definición para término 2

Aunque no son universalmente soportadas, las listas de definiciones son útiles para documentación técnica y glosarios.

Markdown facilita agregar hipervínculos e imágenes mientras mantiene el texto fuente legible.

Enlaces en Línea

La sintaxis de enlace más común usa corchetes para el texto del enlace y paréntesis para la URL:

[Texto del enlace](https://ejemplo.com)
[Enlace con título](https://ejemplo.com "Texto al pasar el cursor")

El texto de título opcional aparece como información sobre herramientas cuando los usuarios pasan el cursor sobre el enlace. Esto es útil para proporcionar contexto adicional sin saturar el texto visible del enlace.

Enlaces de Estilo de Referencia

Para documentos con muchos enlaces o URLs repetidas, los enlaces de estilo de referencia mejoran la legibilidad:

Este es [un enlace][1] y aquí hay [otro enlace][2].

[1]: https://ejemplo.com
[2]: https://ejemplo.com/pagina "Título opcional"

También puedes usar referencias descriptivas en lugar de números:

Visita [Google][google] y [GitHub][gh].

[google]: https://google.com
[gh]: https://github.com

Las definiciones de referencia pueden aparecer en cualquier lugar del documento y no se renderizarán en la salida. Muchos escritores las colocan al final de las secciones o al final del documento.

Enlaces Automáticos

Envuelve URLs o direcciones de correo electrónico en corchetes angulares para crear enlaces automáticos:

<https://ejemplo.com>
<[email protected]>

La mayoría de los analizadores modernos de Markdown también convierten automáticamente URLs desnudas en enlaces clicables, aunque este comportamiento no está garantizado en todas las plataformas.

Imágenes

La sintaxis de imagen es casi idéntica a la sintaxis de enlace, con un prefijo de signo de exclamación:

![Texto alternativo](imagen.jpg)
![Texto alternativo](imagen.jpg "Título de imagen")

El texto alternativo es crucial para la accesibilidad—describe la imagen para usuarios de lectores de pantalla y se muestra cuando la imagen no se carga. Siempre proporciona texto alternativo significativo que transmita el contenido y propósito de la imagen.

La sintaxis de estilo de referencia también funciona para imágenes:

![Logo][logo]

[logo]: /imagenes/logo.png "Logo de la empresa"

Consejo profesional: Markdown estándar no soporta dimensionamiento o alineación de imágenes. Para estas características, necesitarás usar HTML directamente: <img src="imagen.jpg" width="300" alt="Descripción"> o depender de sintaxis extendida de Markdown específica de tu plataforma.

Enlazar Imágenes

Para hacer una imagen clicable, envuelve la sintaxis de imagen en sintaxis de enlace:

[![Texto alternativo](miniatura.jpg)](tamano-completo.jpg)

Esta técnica se usa comúnmente para galerías de imágenes o enlazar miniaturas a versiones de resolución completa.

Bloques de Código y Resaltado de Sintaxis

Markdown sobresale en mostrar código, convirtiéndolo en el formato preferido para documentación técnica y tutoriales de programación.

Código en Línea

Para fragmentos cortos de código dentro del texto, usa comillas invertidas simples:

Usa la función `print()` para mostrar salida.
El archivo `config.json` contiene configuraciones.

Si tu código contiene comillas invertidas, usa comillas invertidas dobles para envolverlo:

``Usa `comillas invertidas` en código``

Bloques de Código Cercados

Para bloques de código de múltiples líneas, usa comillas invertidas triples (```) o tildes triples (~~~) antes y después del código:

```
function saludar(nombre) {
  return `¡Hola, ${nombre}!`;
}
```

Esto crea un bloque de código correctamente formateado con fuente monoespaciada y espacios en blanco preservados.

Resaltado de Sintaxis

Especifica el lenguaje de programación inmediatamente después de las comillas invertidas de apertura para habilitar el resaltado de sintaxis:

```javascript
function saludar(nombre) {
  return `¡Hola, ${nombre}!`;
}
```

```python
def saludar(nombre):
    return f"¡Hola, {nombre}!"
```

```bash
#!/bin/bash
echo "¡Hola, Mundo!"
```