Hoja de Referencia de Markdown: Guía Completa de Sintaxis

· 12 min de lectura

Tabla de Contenidos

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero creado por John Gruber y Aaron Swartz en 2004 que revolucionó la forma en que escribimos para la web. Te permite formatear texto plano usando una sintaxis simple e intuitiva que es tanto legible para humanos como analizable por máquinas.

A diferencia de HTML, que requiere etiquetas verbosas y elementos de cierre, Markdown usa símbolos naturales como asteriscos, almohadillas y corchetes. Esto hace que escribir sea más rápido y el texto fuente sea legible incluso sin renderizar. Un documento Markdown se ve limpio y lógico en su forma cruda, razón por la cual se ha convertido en el estándar universal para documentación técnica.

La filosofía detrás de Markdown es simple: escribir debe ser fácil, y la sintaxis debe ser invisible. Cuando lees un archivo Markdown, estás leyendo contenido primero, marcado segundo. Esto es fundamentalmente diferente de los lenguajes de marcado tradicionales donde las etiquetas a menudo oscurecen el contenido real.

Dónde se Usa Markdown

Markdown se ha vuelto ubicuo en todo el ecosistema tecnológico y más allá:

¿Necesitas convertir tu Markdown a HTML para publicación web? Prueba nuestro convertidor de Markdown a HTML para una conversión instantánea y precisa.

Consejo profesional: Los archivos Markdown usan la extensión .md o .markdown. La mayoría de las plataformas reconocen ambas, pero .md es más común y concisa.

Encabezados y Estructura del Documento

Los encabezados son la columna vertebral de la estructura del documento en Markdown. Crean jerarquía, mejoran la legibilidad y ayudan tanto a humanos como a motores de búsqueda a entender la organización de tu contenido.

Sintaxis Básica de Encabezados

Markdown admite seis niveles de encabezados usando símbolos de almohadilla (#). El número de almohadillas determina el nivel del encabezado:

# Encabezado 1 (H1)
## Encabezado 2 (H2)
### Encabezado 3 (H3)
#### Encabezado 4 (H4)
##### Encabezado 5 (H5)
###### Encabezado 6 (H6)

Cada nivel de encabezado tiene significado semántico. H1 es el título de tu documento, H2 son secciones principales, H3 son subsecciones, y así sucesivamente. Esta jerarquía es crucial para la accesibilidad y el SEO.

Sintaxis Alternativa para H1 y H2

Markdown también admite una sintaxis alternativa de "subrayado" para encabezados H1 y H2:

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

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

Aunque esta sintaxis es válida, la sintaxis de almohadilla es más común y admite los seis niveles de encabezado. La mayoría de los desarrolladores prefieren la consistencia de usar almohadillas en todos sus documentos.

Mejores Prácticas para Encabezados

Consejo rápido: Muchos analizadores de Markdown generan automáticamente enlaces de anclaje desde los encabezados, convirtiendo "Comenzando" a #comenzando. Esto permite enlaces profundos a secciones específicas.

Formato de Texto y Énfasis

Markdown proporciona sintaxis 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.

Texto en Negrita y Cursiva

El énfasis se crea usando asteriscos o guiones bajos:

**Texto en negrita** o __Texto en negrita__
*Texto en cursiva* o _Texto en cursiva_
***Negrita y cursiva*** o ___Negrita y cursiva___

Tanto los asteriscos como los guiones bajos funcionan de manera idéntica, pero los asteriscos son más comunes. Elige un estilo y manténlo para consistencia. Muchas guías de estilo recomiendan asteriscos porque son más fáciles de escribir y más visualmente distintos.

Tachado y Otros Formatos

Las opciones de formato adicionales incluyen:

~~Texto tachado~~
`Código en línea`
==Texto resaltado== (algunos analizadores)
X^2^ (superíndice, algunos analizadores)
H~2~O (subíndice, algunos analizadores)

Ten en cuenta que el texto resaltado, superíndice y subíndice son extensiones no admitidas por todos los analizadores de Markdown. GitHub Flavored Markdown (GFM) admite tachado pero no resaltado por defecto.

Citas en Bloque

Las citas en bloque se crean usando el símbolo mayor que (>):

> Esta es una cita en bloque.
> Puede abarcar múltiples líneas.

>> Las citas en bloque anidadas también son posibles.
>> Solo agrega más símbolos >.

Las citas en bloque son perfectas para citas, frases destacadas o resaltar información importante. Pueden contener otro formato de Markdown, incluyendo encabezados, listas y bloques de código.

Líneas Horizontales

Crea separaciones visuales en tu contenido con líneas horizontales:

---
***
___

Las tres sintaxis producen el mismo resultado. Usa tres o más guiones, asteriscos o guiones bajos en su propia línea. La mayoría de los desarrolladores prefieren guiones (---) por claridad.

Escapar Caracteres Especiales

Para mostrar caracteres literales de Markdown, escápalos con una barra invertida:

\*No en cursiva\*
\# No es un encabezado
\[No es un enlace\]

Esto es esencial cuando necesitas mostrar la sintaxis de Markdown en sí, como en documentación o tutoriales.

Consejo profesional: Al escribir sobre código o temas técnicos, usa formato de código en línea (`comillas invertidas`) para nombres de funciones, variables, rutas de archivos y comandos. Esto mejora la legibilidad y ayuda a los lectores a distinguir el código de la prosa.

Los enlaces e imágenes usan sintaxis similar en Markdown, haciéndolos fáciles de recordar y usar. Ambos admiten formatos en línea y de estilo de referencia para diferentes casos de uso.

Crear Enlaces

La sintaxis básica de enlaces es directa:

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

El texto del enlace aparece entre corchetes, seguido inmediatamente por la URL entre paréntesis. El atributo de título opcional aparece entre comillas después de la URL y se muestra al pasar el cursor.

Enlaces de Estilo de Referencia

Para documentos con muchos enlaces repetidos, los enlaces de estilo de referencia mantienen tu contenido más limpio:

[Texto del enlace][id-referencia]
[Otro enlace][id-referencia]

[id-referencia]: https://ejemplo.com "Título opcional"

Este enfoque separa las definiciones de enlaces del contenido, haciendo la fuente más legible. Es particularmente útil en documentos largos o cuando la misma URL aparece múltiples veces.

Enlaces Automáticos

Las URLs y direcciones de correo electrónico pueden convertirse automáticamente en enlaces:

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

Muchos analizadores de Markdown también enlazan automáticamente URLs sin corchetes angulares, pero este comportamiento no es universal. Usar corchetes angulares asegura un comportamiento consistente entre plataformas.

Agregar Imágenes

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

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

[referencia-imagen]: imagen.jpg "Título opcional"

El texto alternativo es crucial para la accesibilidad y el SEO. Describe la imagen para lectores de pantalla y aparece si la imagen no se carga. Siempre proporciona texto alternativo significativo que describa el contenido y contexto de la imagen.

Tamaño y Alineación de Imágenes

Markdown estándar no admite tamaño o alineación de imágenes. Necesitarás usar HTML para estas características:

<img src="imagen.jpg" alt="Texto alternativo" width="300">
<img src="imagen.jpg" alt="Texto alternativo" style="float:right;margin:10px">

La mayoría de los analizadores de Markdown permiten HTML en línea, haciendo de esta una solución práctica cuando necesitas más control sobre la presentación de imágenes.

Consejo rápido: Al enlazar a páginas internas, usa URLs relativas (/acerca-de/) en lugar de URLs absolutas (https://ejemplo.com/acerca-de/). Esto hace que tu contenido sea portable y funcione correctamente en entornos de desarrollo.

Listas: Ordenadas, Desordenadas y de Tareas

Las listas son fundamentales para organizar información en Markdown. Son simples de crear y admiten anidamiento para jerarquías complejas.

Listas Desordenadas

Crea listas con viñetas usando asteriscos, guiones o signos más:

* Elemento uno
* Elemento dos
* Elemento tres

- Elemento uno
- Elemento dos
- Elemento tres

+ Elemento uno
+ Elemento dos
+ Elemento tres

Los tres símbolos funcionan de manera idéntica. Elige uno y úsalo consistentemente en todo tu documento. La mayoría de los desarrolladores prefieren guiones por su claridad visual.

Listas Ordenadas

Las listas numeradas usan números seguidos de puntos:

1. Primer elemento
2. Segundo elemento
3. Tercer elemento

Aquí hay una característica útil: los números reales no importan. Markdown renumera automáticamente tu lista cuando se renderiza:

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

Esto hace que reordenar elementos sea más fácil ya que no necesitas renumerar todo manualmente. Sin embargo, comenzar con 1. para cada elemento puede ser confuso al leer la fuente.

Listas Anidadas

Crea listas jerárquicas indentando elementos con espacios o tabulaciones:

1. Primer elemento
   - Viñeta anidada
   - Otra viñeta anidada
2. Segundo elemento
   1. Número anidado
   2. Otro número anidado
      - Anidamiento aún más profundo

Usa indentación consistente (típicamente 2-4 espacios) para cada nivel de anidamiento. La mayoría de los analizadores son flexibles, pero la consistencia mejora la legibilidad.

Listas de Tareas

GitHub Flavored Markdown introdujo listas de tareas para rastrear pendientes:

- [ ] Tarea sin marcar
- [x] Tarea marcada
- [ ] Otra tarea sin marcar

Las listas de tareas son interactivas en plataformas como GitHub—puedes marcar y desmarcar elementos directamente en la vista renderizada. Son perfectas para planificación de proyectos, seguimiento de issues y documentos colaborativos.

Mejores Prácticas para Listas

Código y Bloques de Código

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

Código en Línea

Envuelve el código en línea con comillas invertidas simples:

Usa la función `console.log()` para depurar.
El elemento `<div>` es un contenedor.

El formato de código en línea preserva el espaciado y previene la interpretación de Markdown. Es esencial para mencionar elementos de código dentro de oraciones.

Bloques de Código

Crea bloques de código usando triple comillas invertidas (bloques de código cercados):

```
function hola() {
  console.log("Hola, mundo!");
}
```

Esta es la sintaxis moderna y preferida. Es más limpia y flexible que el método de indentación antiguo (4 espacios o 1 tabulación).

Resaltado de Sintaxis

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

```javascript
function hola() {
  console.log("Hola, mundo!");
}
```

```python
def hola():
    print("Hola, mundo!")
```

```css
.contenedor {
  max-width: 1200px;
  margin: 0 auto;
}
```

La mayoría de los analizadores de Markdown admiten docenas de lenguajes. Los identificadores comunes incluyen

We use cookies for analytics. By continuing, you agree to our Privacy Policy.