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?
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.
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.mdque 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.
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.
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.
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
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.
Primer párrafo.
Segundo párrafo, separado por una línea en blanco. Este renglón se junta con el de arriba.
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~~.
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
- Frutas
- Mango
- Papaya
- Verduras
- Precalienta el horno
- Mezcla los ingredientes
- 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). 
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.
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)
```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.
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.
- [ ] pendientey- [x] hechose 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
mermaidse 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 ```
- Comprar boletos
- Reservar hotel
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ítuloo-elementono funcionan: después de#,-o1.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_finalo una operación como2*3*4pueden 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:
 - 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.
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).
