Sintaxis básica de Markdown: guía completa con ejemplos
Domina todos los elementos de la sintaxis básica de Markdown con ejemplos claros y errores comunes que debes evitar. Tu referencia definitiva para encabezados, listas, enlaces y más.
La sintaxis básica de Markdown es la base que todo desarrollador, escritor y creador de contenido necesita dominar. Ya sea que estés escribiendo documentación, redactando una publicación de blog o formateando un issue en GitHub, estos elementos fundamentales son las herramientas que utilizarás todos los días.
Esta guía recorre cada elemento de la sintaxis básica con ejemplos claros, comparaciones con la salida HTML y errores comunes que debes evitar. Guárdala en tus favoritos — volverás a consultarla más a menudo de lo que crees.
Encabezados
Los encabezados estructuran tu contenido en una jerarquía lógica. Markdown admite seis niveles de encabezados, que se crean colocando símbolos # antes del texto.
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
Esto produce el siguiente HTML:
<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>
Buenas prácticas para encabezados
Siempre añade un espacio entre el # y el texto del encabezado. Sin el espacio, algunos procesadores no lo reconocerán como encabezado.
✅ ## This Works
❌ ##This Doesn't
Usa los encabezados en orden. No saltes de H2 a H4 — esto rompe el esquema lógico del documento y perjudica tanto la accesibilidad como el SEO. Piensa en los encabezados como una tabla de contenidos: cada nivel debe anidarse de forma lógica bajo el nivel superior.
Usa solo un H1 por página. El H1 es el título de tu página. Todo lo demás debe ser H2 o inferior.
Párrafos y saltos de línea
Los párrafos son el elemento más simple de Markdown — solo escribe texto. Separa los párrafos con una línea en blanco.
This is the first paragraph.
This is the second paragraph.
Saltos de línea
Aquí es donde muchos principiantes se confunden. Presionar Enter una vez no crea una nueva línea en la mayoría de los renderizadores de Markdown. Necesitas hacer una de estas dos cosas:
- Terminar una línea con dos o más espacios (y luego presionar Enter)
- Usar la etiqueta HTML
<br>
This is the first line.
This is the second line.
Or use HTML:<br>
This starts a new line.
Error común
Simplemente presionar Enter entre dos líneas las fusionará en un solo párrafo en la salida renderizada:
Line one
Line two
Esto se renderiza como: "Line one Line two" — una sola línea. Siempre usa una línea en blanco para un nuevo párrafo o espacios al final para un salto de línea dentro del mismo párrafo.
Formato de texto
Markdown facilita enormemente el énfasis en el texto. Estas son las opciones principales de formato:
Negrita
Envuelve el texto con doble asterisco o doble guion bajo:
**This is bold text**
__This is also bold__
Salida HTML: <strong>This is bold text</strong>
Cursiva
Envuelve el texto con un solo asterisco o un solo guion bajo:
*This is italic text*
_This is also italic_
Salida HTML: <em>This is italic text</em>
Negrita y cursiva
Combina tres asteriscos para ambas:
***Bold and italic***
___Also bold and italic___
**_Or mix like this_**
Salida HTML: <strong><em>Bold and italic</em></strong>
Tachado
Usa doble virgulilla (esta es una extensión de GFM, pero es compatible en casi todas partes):
~~This text is crossed out~~
Salida HTML: <del>This text is crossed out</del>
Error común
Mezclar guiones bajos en el medio de una palabra no funciona de forma fiable. Usa asteriscos para el énfasis dentro de palabras:
✅ This is**very**important
❌ This is__very__important
Citas en bloque
Las citas en bloque se crean con el carácter >. Se usan comúnmente para citar fuentes, resaltar notas importantes o destacar información clave.
> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber
Salida HTML:
<blockquote>
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
— John Gruber</p>
</blockquote>
Citas de varios párrafos
Añade > en la línea en blanco entre párrafos:
> First paragraph of the quote.
>
> Second paragraph of the quote.
Citas anidadas
Usa >> para anidar:
> This is the outer quote.
>
>> This is a nested quote inside it.
Citas con otros elementos
Puedes combinar citas en bloque con otros formatos de Markdown:
> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.
Listas
Las listas son uno de los elementos de Markdown más utilizados. Encontrarás tres tipos: sin orden, ordenadas y listas de tareas.
Listas sin orden
Usa -, * o + como marcadores. Elige uno y mantenlo por consistencia:
- First item
- Second item
- Third item
Salida HTML:
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
Listas ordenadas
Usa números seguidos de un punto. Los números reales no importan — Markdown los numera automáticamente:
1. First step
2. Second step
3. Third step
Curiosamente, esto produce la misma salida:
1. First step
1. Second step
1. Third step
Ambos se renderizan como una lista correctamente numerada 1-2-3. Sin embargo, la mejor práctica es usar números secuenciales para facilitar la lectura del archivo fuente.
Listas anidadas
Indenta con dos o cuatro espacios para crear sublistas:
1. Main item
- Sub-item A
- Sub-item B
- Sub-sub-item
2. Another main item
Listas de tareas
Las listas de tareas (una funcionalidad de GFM) usan - [ ] para elementos sin marcar y - [x] para elementos marcados:
- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish
Error común
Olvidar la línea en blanco antes de una lista cuando sigue a un párrafo. Algunos procesadores la requieren:
✅ Here is my list:
- Item one
- Item two
❌ Here is my list:
- Item one
- Item two
Código
Mostrar código es una de las funciones más potentes de Markdown, y hacerlo correctamente es importante para la legibilidad.
Código en línea
Envuelve el código entre comillas invertidas simples para mostrarlo en línea:
Use the `print()` function to output text.
Salida HTML: Use the <code>print()</code> function to output text.
Si tu código contiene una comilla invertida, usa comillas invertidas dobles:
``There is a literal `backtick` here.``
Bloques de código
Para código multilínea, usa triple comilla invertida (bloques de código delimitados) con un identificador de lenguaje opcional para el resaltado de sintaxis:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
El identificador de lenguaje (javascript, python, html, css, bash, etc.) habilita el resaltado de sintaxis en la mayoría de los renderizadores. Inclúyelo siempre — mejora drásticamente la legibilidad.
Bloques de código indentados
También puedes crear bloques de código indentando cada línea con cuatro espacios o un tabulador:
function add(a, b) {
return a + b;
}
Sin embargo, los bloques de código delimitados son muy preferibles porque admiten resaltado de sintaxis y no requieren que cada línea esté indentada.
Enlaces
Los enlaces son esenciales para conectar contenido. Markdown admite varios formatos de enlace.
Enlaces en línea
El formato más común — texto entre corchetes, URL entre paréntesis:
[Visit Example](https://example.com)
Salida HTML: <a href="https://example.com">Visit Example</a>
Enlaces con títulos
Añade un título entre comillas después de la URL (aparece como tooltip al pasar el cursor):
[Visit Example](https://example.com "Example Website")
Enlaces de estilo referencia
Para un texto fuente más limpio cuando tienes muchos enlaces, usa el estilo referencia:
I use [Google][1] and [GitHub][2] daily.
[1]: https://google.com "Google"
[2]: https://github.com "GitHub"
Esto mantiene tus párrafos limpios y agrupa todas las URLs al final — especialmente útil en documentos largos.
Enlaces automáticos
Envuelve una URL o correo electrónico entre corchetes angulares para crear un enlace automático:
<https://example.com>
<contact@example.com>
La mayoría de los renderizadores modernos (como GitHub) también enlazan automáticamente URLs sin corchetes angulares, pero usarlos garantiza la compatibilidad.
Error común
Olvidar que los espacios en las URLs necesitan codificación. Usa %20 para los espacios:
✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)
Imágenes
Las imágenes usan la misma sintaxis que los enlaces, pero con un signo de exclamación ! delante:
Salida HTML: <img src="/path/to/image.webp" alt="Alt text describing the image">
Imágenes con títulos
Imágenes con enlace
Combina la sintaxis de enlace e imagen para hacer una imagen clicable:
[](https://example.com)
Buenas prácticas para el texto alternativo
Siempre escribe un texto alternativo descriptivo. Cumple dos propósitos fundamentales:
- Accesibilidad — los lectores de pantalla lo usan para describir las imágenes a usuarios con discapacidad visual
- SEO — los motores de búsqueda lo usan para comprender el contenido de la imagen
✅ 
❌ 
❌ 
Líneas horizontales
Crea una línea horizontal (separador temático) para separar secciones visualmente. Usa tres o más guiones, asteriscos o guiones bajos:
---
***
___
Los tres producen el mismo HTML: <hr>
Mejor práctica: Usa --- de forma consistente y siempre añade líneas en blanco antes y después:
Content above the rule.
---
Content below the rule.
Caracteres de escape
¿Qué pasa si quieres mostrar un asterisco literal o un símbolo de almohadilla sin activar el formato de Markdown? Usa una barra invertida \ antes del carácter:
\* This is not italic \*
\# This is not a heading
\- This is not a list item
Aquí tienes la lista completa de caracteres que puedes escapar:
\ Backslash
` Backtick
* Asterisk
_ Underscore
{} Curly braces
[] Square brackets
() Parentheses
# Hash
+ Plus sign
- Hyphen
. Dot
! Exclamation mark
| Pipe
Hoja de referencia rápida
Aquí tienes cada elemento de la sintaxis básica en una tabla para consulta rápida:
Element Syntax HTML
-------------- ------------------ -----------
Heading 1 # Text <h1>
Heading 2 ## Text <h2>
Heading 3 ### Text <h3>
Bold **text** <strong>
Italic *text* <em>
Bold + Italic ***text*** <strong><em>
Strikethrough ~~text~~ <del>
Blockquote > text <blockquote>
Ordered list 1. item <ol><li>
Unordered list - item <ul><li>
Inline code `code` <code>
Link [text](url) <a href>
Image  <img>
Horizontal rule --- <hr>
Line break spaces + Enter <br>
Ponlo en práctica
Ahora que has aprendido todos los elementos de la sintaxis básica de Markdown, es hora de usarlos. Esto es lo que puedes hacer a continuación:
-
Practica escribiendo: Crea un archivo
notes.mdy prueba cada elemento de sintaxis. Cuanto más escribas, más natural se volverá. -
Usa una herramienta de vista previa: La vista previa integrada de Markdown en VS Code (
Ctrl+Shift+V/Cmd+Shift+V) te permite ver la salida renderizada en tiempo real mientras escribes. -
Convierte y comparte: Cuando tu documento Markdown esté listo para el mundo, transfórmalo en una salida pulida — convierte Markdown a HTML para publicación web, genera un PDF para documentos listos para imprimir, o exporta a Word para edición colaborativa.
-
Explora más: Una vez que te sientas cómodo con la sintaxis básica, adéntrate en nuestra guía de sintaxis extendida de Markdown para tablas, notas al pie, listas de definiciones y más. ¿Nuevo en Markdown? Comienza con ¿Qué es Markdown? para obtener una visión general.
La belleza de Markdown es que estos elementos básicos cubren la gran mayoría de todo lo que necesitarás escribir. Domínalos una vez y los usarás en todas partes — desde GitHub hasta Notion, desde documentación hasta publicaciones de blog como esta.