Markdown: escribe con formato usando solo texto (guía para principiantes)

Markdown es una forma de dar formato a un texto usando solo signos del teclado: pones dos asteriscos alrededor de una palabra y sale en negritas, empiezas un renglón con un guion y se vuelve una lista. Lo escribes en cualquier bloc de notas, se lee bien aunque nadie lo convierta, y cuando un programa que lo entiende lo muestra, aparece con su formato. Esta guía te lo enseña desde cero, con un editor para practicar y, al final, una pregunta que hoy se discute mucho: ¿no sería mejor usar HTML?

Para quién es. Para cualquiera que escriba en GitHub, en una app de notas, en Discord o que copie respuestas de un chat de IA. No necesitas saber programar: si sabes escribir un correo, puedes escribir Markdown.

Qué es Markdown

Markdown lo creó el escritor y programador John Gruber en 2004, con ayuda de Aaron Swartz en el diseño de la sintaxis. Su versión 1.0.1 salió el 17 de diciembre de ese año. Gruber quería escribir para internet sin llenar el texto de etiquetas de HTML como <strong> o <a href="…">. Su meta, en sus palabras: que el formato fuera «tan legible como sea posible», al grado de que un documento en Markdown se pudiera publicar tal cual, como texto simple, sin que pareciera lleno de marcas.

La idea es sencilla: tú escribes texto con unos cuantos signos, y un programa lo convierte en formato. Ese programa casi siempre lo convierte a HTML, el lenguaje de las páginas web, y por eso Markdown y HTML van de la mano, como verás al final.

Escribes texto, ves formatoLos signos le dicen al programa cómo mostrarloLO QUE ESCRIBES# Lista del súper**Urgente:** leche- huevos- pan *integral*[La receta](https://…)se convierte enLO QUE SE VELista del súperUrgente: lechehuevospan integralLa receta
Lo que escribes en Markdown y cómo se ve después de convertirlo. Gráfica: decodigo.com.

Los archivos de Markdown suelen terminar en .md, como LEEME.md o notas.md. Por dentro son texto simple: los abre cualquier editor, pesan poquito y no dependen de ningún programa en particular.

Dónde lo vas a encontrar

Aunque no lo sepas, probablemente ya lo viste:

  • GitHub y GitLab. Casi todos los proyectos de programación tienen un archivo README.md que explica qué hacen; es Markdown. También los comentarios, los issues y las wikis.
  • Chats de IA. ChatGPT, Claude, Gemini y compañía responden con Markdown: por eso a veces, al copiar una respuesta a otro lado, aparecen asteriscos y almohadillas sueltos.
  • Apps de notas. Obsidian guarda tus notas como archivos .md; Notion entiende sus atajos mientras escribes.
  • Foros y mensajería. Reddit y Discord aceptan buena parte de Markdown en sus mensajes.
  • Documentación y blogs. Muchos sitios de documentación y generadores de páginas se escriben en Markdown y se publican como HTML.

Ojo: no todos hablan exactamente el mismo Markdown. Hay «sabores». El caso más conocido es WhatsApp: su formato se parece, pero no es Markdown. Según su centro de ayuda, ahí la negrita va con un asterisco (*hola*), la cursiva con guion bajo (_hola_) y el tachado con una virgulilla (~hola~); también admite código con acentos graves, listas y citas, pero no títulos ni enlaces con texto.

Mismo idioma, distinto acentoGitHub usa Markdown; WhatsApp, algo parecidoGitHubWhatsAppNegrita**hola***hola*Cursiva*hola*_hola_Tachado~~hola~~~hola~Código`hola``hola`Título# Holano existeEnlace[hola](url)no existeCambia el signo: lo que es negrita enWhatsApp es cursiva en GitHub.
Los mismos estilos en GitHub (Markdown) y en WhatsApp, según la ayuda de cada uno. Gráfica: decodigo.com.

Pruébalo aquí mismo

A la izquierda escribes Markdown y a la derecha ves el resultado al instante. Ya trae un ejemplo: cámbialo, bórralo o pega tu propio texto. Todo pasa en tu navegador; no se envía nada a ningún servidor. Con Copiar el HTML te llevas el resultado convertido a HTML, listo para pegarlo en una página.

Se ve así (vista previa)

Este editor necesita JavaScript. Sin él, puedes practicar en cualquier bloc de notas y revisar el resultado en un sitio que entienda Markdown, como GitHub.

Sobre este editor. Es un conversor pequeño, hecho para aprender: entiende todo lo que explica esta guía, pero no cada rincón de las reglas oficiales. Por seguridad no deja pasar HTML ni enlaces raros (los que empiezan con javascript:, por ejemplo): si los escribes, se muestran como texto o tachados. Las tablas se muestran como lista.

Lo básico, paso a paso

Estas son las piezas que vas a usar el 90 % del tiempo. Cada una trae lo que se escribe y cómo se ve. Puedes copiar cualquier ejemplo al editor de arriba para jugar con él.

Encabezados

Un renglón que empieza con # y un espacio es un título. Con dos ## es un subtítulo, con tres un subtítulo más chico, y así hasta seis. El espacio después de la almohadilla es obligatorio: #Hola sin espacio no es título.

# Viaje a Oaxaca
## Qué llevar
### Para la playa
Así se ve
Viaje a Oaxaca
Qué llevar
Para la playa

Párrafos y saltos de línea

Para separar párrafos deja una línea en blanco entre ellos. Aquí está la trampa más común de Markdown: si solo das un Enter, los dos renglones se juntan en uno. Para forzar un salto sin empezar párrafo nuevo, termina el renglón con dos espacios o con una barra invertida \.

Primer párrafo.

Segundo párrafo, separado por una línea en blanco.
Este renglón se junta con el de arriba.
Así se ve

Primer párrafo.

Segundo párrafo, separado por una línea en blanco. Este renglón se junta con el de arriba.

El salto de línea que no saleUn solo Enter no basta en un archivo .mdUn Enter: se juntanHolaAdiósHola AdiósLínea en blanco: párrafo nuevoHolaAdiósHolaAdiósDos espacios al final (··)Hola··AdiósHolaAdiósBarra invertida al finalHola\AdiósHolaAdiósEn los chats y comentarios de GitHub,un solo Enter sí hace salto.
Por qué un solo Enter no hace salto de línea en un archivo .md, y tres formas de lograrlo. Gráfica: decodigo.com.

Negritas, cursivas y tachado

Rodea las palabras con signos: dos asteriscos para negrita, uno para cursiva. También sirve el guion bajo (__negrita__ y _cursiva_), pero los asteriscos son más comunes. Tres asteriscos dan negrita y cursiva a la vez. El tachado con ~~ no es del Markdown original, pero lo entienden GitHub y casi todas las apps.

El examen es **mañana**, no *pasado mañana*.
Ya no se usa ~~fax~~.
Así se ve

El examen es mañana, no pasado mañana. Ya no se usa fax.

Listas

Para una lista con viñetas, empieza cada renglón con un guion y un espacio (también sirven * o +). Para una numerada, usa un número y un punto. Si dejas dos espacios al inicio, el elemento queda dentro del de arriba.

- Frutas
  - Mango
  - Papaya
- Verduras

1. Precalienta el horno
2. Mezcla los ingredientes
3. Hornea 30 minutos
Así se ve
  • Frutas
    • Mango
    • Papaya
  • Verduras
  1. Precalienta el horno
  2. Mezcla los ingredientes
  3. Hornea 30 minutos

Enlaces e imágenes

Un enlace se escribe con el texto entre corchetes y la dirección entre paréntesis, pegados. Una imagen es igual, pero con un signo de admiración al principio; lo que va entre corchetes es la descripción, que leen los lectores de pantalla y que aparece si la imagen no carga. Si solo quieres que una dirección se vuelva clic, ponla entre < y >.

Consulta el [clima de hoy](https://www.smn.conagua.gob.mx).
![Volcán Popocatépetl al amanecer](https://ejemplo.com/popo.jpg)
Así se ve

Consulta el clima de hoy.
[aquí aparecería la foto del volcán]

Citas

Un renglón que empieza con > es una cita: se ve con una barra a un lado. Sirve para citar a alguien o para responder un mensaje.

> La imaginación es más importante que el conocimiento.
Así se ve
La imaginación es más importante que el conocimiento.

Código

Para un pedazo de código dentro de una frase, rodéalo con acentos graves (`, la tecla que suele estar junto al 1 o junto a la Ñ). Para un bloque de varios renglones, ponlo entre dos renglones con tres acentos graves; si después de los tres primeros escribes el lenguaje, muchos sitios lo colorean. Dentro del código nada se convierte: los asteriscos se quedan como asteriscos.

Para instalarlo escribe `pip install requests` y luego:

```python
import requests
print(requests.get("https://ejemplo.com").status_code)
```
Así se ve

Para instalarlo escribe pip install requests y luego:

import requests
print(requests.get("https://ejemplo.com").status_code)

Líneas horizontales

Tres guiones solos en un renglón, con una línea en blanco arriba, dibujan una raya que separa secciones. También sirven tres asteriscos o tres guiones bajos.

Fin de la primera parte.

---

Empieza la segunda.
Así se ve

Fin de la primera parte.


Empieza la segunda.

Los extras de GitHub

El Markdown de Gruber es pequeño a propósito, y cada sitio le fue agregando cosas. Para poner orden, en 2014 nació CommonMark, una especificación que define con precisión cada regla, porque la descripción original, según su propio sitio, no era del todo clara y cada programa la interpretaba distinto. GitHub usa su propia versión, basada en CommonMark, con estos extras:

  • Casillas de tareas. - [ ] pendiente y - [x] hecho se ven como casillas, vacías o marcadas.
  • Tachado con ~~texto~~ (y también con una sola virgulilla).
  • Alertas. Una cita que empieza con [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] o [!CAUTION] se ve como un recuadro de nota, consejo, importante, advertencia o precaución.
  • Notas al pie. Escribes [^1] en el texto y en otro lado [^1]: Tu nota.; GitHub la manda al final.
  • Diagramas. Un bloque de código marcado como mermaid se dibuja como diagrama de flujo.
  • Tablas. Se escriben con barras verticales y una fila de guiones bajo los títulos.
- [x] Comprar boletos
- [ ] Reservar hotel

> [!WARNING]
> El vuelo sale a las 6:00, llega con tiempo.

| Ciudad  | Noches |
|---------|--------|
| Oaxaca  | 3      |
| Puebla  | 2      |

```mermaid
graph LR
  CDMX --> Puebla --> Oaxaca
```
Así se ve (en GitHub)
  • Comprar boletos
  • Reservar hotel
Advertencia

El vuelo sale a las 6:00, llega con tiempo.

La tabla se ve como una cuadrícula con dos columnas, Ciudad y Noches, y el bloque de Mermaid como un diagrama con tres cajas unidas por flechas: CDMX, Puebla y Oaxaca.

Estos extras funcionan en GitHub y en varias apps, pero no en todas partes: si escribes para otro sitio, prueba antes cómo se ven.

Errores típicos

  • Los renglones se juntan. Un solo Enter no hace salto en un archivo .md. Deja una línea en blanco o termina con dos espacios. (En los comentarios de GitHub y en muchos chats, un Enter sí basta.)
  • Falta el espacio. #Título o -elemento no funcionan: después de #, - o 1. va un espacio.
  • Falta la línea en blanco. Una lista o un título pegados al párrafo de arriba a veces no se reconocen. Ante la duda, deja una línea en blanco antes y después.
  • La numeración «no me hace caso». En una lista numerada solo cuenta el primer número: si escribes 1, 1, 1, sale 1, 2, 3. Y si empiezas en 5, la lista empieza en 5.
  • Un signo se vuelve formato sin querer. Un archivo llamado mi_archivo_final o una operación como 2*3*4 pueden salir en cursiva en algunos sitios. Pon una barra invertida antes del signo (\*, \_, \#) o mételo en código con acentos graves.
  • Un enlace que no se convierte. Entre los corchetes y los paréntesis no puede haber espacio: [texto] (url) no funciona, [texto](url) sí.
  • Se ve bien aquí y mal allá. Es el problema de los sabores: lo que funciona en GitHub puede no funcionar en WhatsApp o en otra app. Si importa cómo se ve, prueba en el lugar donde se va a publicar.
  • Asteriscos sueltos al copiar de un chat de IA. Copiaste el Markdown «crudo». Pégalo en un lugar que entienda Markdown, o pide la respuesta sin formato.

Chuleta

  • Título grande / mediano: # Título ## Subtítulo
  • Negrita: **texto**
  • Cursiva: *texto* o _texto_
  • Tachado (GitHub): ~~texto~~
  • Lista con viñetas: - elemento
  • Lista numerada: 1. elemento
  • Casilla (GitHub): - [ ] pendiente - [x] hecho
  • Enlace: [texto](https://…)
  • Imagen: ![descripción](https://…/foto.png)
  • Cita: > texto
  • Código en línea: `código`
  • Bloque de código: ```python … ```
  • Línea horizontal: ---
  • Salto de línea: dos espacios al final, o \
  • Párrafo nuevo: una línea en blanco
  • Mostrar un signo tal cual: \* \# \_

Para profundizar, la guía oficial de GitHub y el sitio de CommonMark tienen todas las reglas. Si trabajas con proyectos de programación, Markdown va de la mano con Git, y si te interesan otros formatos de texto con estructura, mira nuestra guía de JSON y XML.

¿Y si mejor HTML?

Hay una ironía en todo esto: Markdown casi siempre termina convertido en HTML. Es lo que hace el editor de arriba, y lo que hacen GitHub y los blogs. Gruber lo dijo desde el principio: Markdown «no es un sustituto de HTML, ni se le acerca»; su sintaxis cubre solo una parte muy pequeña de las etiquetas de HTML, y para lo que no cubre, según su propia documentación, «simplemente usas HTML». De hecho, en muchos sitios puedes escribir HTML dentro de un archivo Markdown.

En 2026 la pregunta se volteó: ¿y si, en lugar de Markdown, usamos HTML directamente? En mayo, Thariq Shihipar, del equipo de Claude Code en Anthropic, publicó un texto titulado «The Unreasonable Effectiveness of HTML» en el que cuenta que pide a la IA sus planes, reportes y revisiones de código en HTML y no en Markdown. Sus razones:

  • Con agentes de IA cada vez más capaces, Markdown se le volvió «un formato cada vez más restrictivo».
  • Le cuesta leer un archivo de Markdown de «más de cien líneas», y difícilmente logra que alguien más de su empresa lo lea.
  • Los archivos de Markdown «son difíciles de compartir», porque la mayoría de los navegadores no los muestran bien; un HTML lo abre cualquiera.
  • Con HTML, la IA puede agregar diagramas, colores y botones, y él siente que se mantiene «mucho más al tanto» de lo que hace la IA, en vez de aprobar planes sin leerlos.

El programador Simon Willison, que difundió el texto, contó que pedía casi todo en Markdown desde la época de GPT-4, cuando los modelos solo podían manejar unos 8,192 tokens y el ahorro de Markdown valía mucho. Con modelos que hoy aceptan mucho más texto, dice, pedir HTML permite que la respuesta traiga diagramas SVG, elementos interactivos y navegación dentro de la página.

¿Markdown o HTML?El mismo texto escrito de las dos formasMarkdown · 31 caracteres**Hola** [mundo](https://ej.mx)HTML · 55 caracteres<strong>Hola</strong><a href="https://ej.mx">mundo</a>Markdown gana en…Leerse bien aunque no se conviertaEscribirse rápido, a manoCambios fáciles de comparar en GitOcupar menos espacio y tokensHTML gana en…Diseño, colores y acomodo libreBotones, pestañas y gráficasAbrirse en cualquier navegadorHacer lo que Markdown no prevé
El mismo texto en Markdown y en HTML, y en qué gana cada uno. Gráfica: decodigo.com.

No todos están de acuerdo. Las críticas que recoge InfoQ: con HTML se pierde la sencillez del texto simple, el archivo «crudo» es mucho más difícil de leer, ocupa más tokens (cuesta más y llena antes la memoria del modelo), sus cambios se comparan peor en Git y mostrar HTML generado por una IA tiene riesgos de seguridad si no se aísla. El propio Shihipar reconoce que Markdown suele gastar menos tokens y que él está «en el extremo» de los fanáticos del HTML.

Entonces, ¿HTML va a sustituir a Markdown? Para algunas cosas, probablemente sí: reportes, explicaciones largas o páginas que genera una IA para que tú las leas o las compartas, donde importan el diseño y la interactividad. Para lo que escribes a mano, como notas, un README, un mensaje o la documentación de un proyecto, Markdown sigue siendo más rápido de escribir y más fácil de leer en crudo. Lo más útil es conocer los dos: Markdown para escribir rápido, HTML cuando necesitas control total. Si quieres dar ese paso, empieza por nuestra sección de HTML y CSS.

Fuentes: John Gruber, Markdown y su sintaxis (Daring Fireball); CommonMark; GitHub Docs, «Basic writing and formatting syntax»; WhatsApp, «Cómo dar formato a tus mensajes»; Thariq Shihipar, «Using Claude Code: The Unreasonable Effectiveness of HTML» (mayo de 2026); Simon Willison (8 de mayo de 2026); InfoQ (24 de junio de 2026). Logotipo de Markdown en la portada: Markdown Mark de Dustin Curtis, dominio público (CC0).