Introducción

Markdown es un lenguaje de marcado ligero que permite aplicar formato a texto plano de manera sencilla y rápida. Fue creado por John Gruber en 2004 con el objetivo de facilitar la escritura de contenido para la web, manteniendo una sintaxis legible tanto para humanos como para máquinas.

Gracias a su simplicidad, Markdown se ha convertido en una herramienta fundamental en la redacción de documentación técnica, blogs, archivos README en proyectos de GitHub, apuntes académicos y publicaciones en plataformas como Jekyll, Hugo, Obsidian o Notion.

Conocimiento previo

• Conceptos básicos de HTML

Referencias

• CommonMark - Especificación estándar y referencia oficial de Markdown
• Markdown Guide - Guía completa y práctica para aprender Markdown
• MDX documentation - Documentación oficial para MDX, integración de Markdown y JSX

Índice

1. Qué es Markdown
2. Estructura de los ficheros
   2.1. Extensiones: .md y .mdx
3. Sintaxis básica
   3.1. Encabezados
   3.2. Párrafos y saltos de línea
   3.3. Énfasis: negrita y cursiva
   3.4. Listas
   3.5. Enlaces e imágenes
   3.6. Citas y bloques de código
   3.7. Reglas horizontales
4. Sintaxis avanzada
   4.1. Tablas
   4.2. Notas de pie de página
   4.3. Anclajes
   4.4. Listas de definición
   4.5. Listas de tareas
   4.6. Tachado
   4.7. Emojis
   4.8. Resaltado
   4.9. Subíndice y superíndice
   4.10 Markdown + HTML
5. Herramientas para trabajar con MarkDown
6. Ejercicios

1. Qué es Markdown

Markdown es un lenguaje de marcado ligero que permite aplicar formato a texto plano de forma sencilla y legible. Fue creado por John Gruber en 2004 con el objetivo de que los textos escritos en Markdown pudieran convertirse fácilmente a HTML y, al mismo tiempo, fueran cómodos de leer directamente en su versión sin procesar.

Se utiliza ampliamente en la creación de documentación técnica, blogs, archivos README de proyectos, publicaciones académicas, entre otros. Su principal ventaja es que reduce la complejidad de los lenguajes de marcado tradicionales como HTML o LaTeX, permitiendo concentrarse en el contenido sin preocuparse por el estilo o la estructura del código.

Cuando hablamos de Markdown, podemos distinguir dos conceptos importantes: Markdown estándar y Markdown extendido.

• Markdown estándar se refiere a la sintaxis original definida por John Gruber y Aaron Swartz. Incluye los elementos básicos como encabezados, listas, enlaces, imágenes, énfasis en texto (negrita, cursiva), bloques de código y reglas horizontales. Esta versión básica es compatible con la mayoría de los procesadores Markdown y garantiza máxima portabilidad y simplicidad.

• Markdown extendido es una evolución que añade funcionalidades adicionales para cubrir necesidades más avanzadas en la creación de documentos. Estas extensiones pueden incluir elementos como listas de definición, tablas, notas al pie, emojis, resaltado de texto, listas de tareas, subíndices, superíndices, entre otros. Sin embargo, no todos los procesadores soportan estas características y pueden variar entre plataformas.

Por ejemplo, GitHub y GitLab usan una versión extendida conocida como GitHub Flavored Markdown (GFM), que soporta tablas y listas de tareas, mientras que otras plataformas pueden tener sus propias extensiones o limitaciones.

2. Estructura de los ficheros

Un fichero Markdown es simplemente un archivo de texto plano que contiene contenido estructurado usando la sintaxis Markdown. A diferencia de los archivos .docx o .odt, los archivos Markdown no contienen estilos visuales integrados, solo instrucciones de estructura (como “esto es un título”, “esto es una lista”, “esto es un enlace”).

Un archivo Markdown puede contener:

• Títulos o encabezados, usando #
• Párrafos de texto plano
• Listas, numeradas o con viñetas
• Enlaces y imágenes
• Tablas
• Bloques de código
• Citas

Opcionalmente, puede haber al inicio del fichero una sección inicial llamada frontmatter entre ---, donde se a`aden metadatos como el título, el autor, la fecha o etiquetas del contenido (esto es útil en sistemas como Astro)

Ejemplo de un fichero básico:

---
title: "Ejemplo de Markdown"
author: "José Luis Ferrer"
---

2.1. Extensiones: .md y .mdx

La extensión .md indica que se trata de un archivo escrito en Markdown estándar. Estos archivos son compatibles con la mayoría de editores de texto y plataformas de documentación (como GitHub, Obsidian, Typora, VSCode, etc.).

Al abrir un .md, verás texto plano con símbolos como #, *, -, etc., que representan la estructura del contenido. No es necesario compilarlo ni transformarlo para poder leerlo, aunque normalmente se visualiza mejor en un renderizador de Markdown, que interpreta la sintaxis y la muestra con estilo.

La extensión .mdx permite escribir Markdown combinado con componentes de React. Es decir, puedes mezclar texto formateado con elementos interactivos, botones, tarjetas o gráficos, integrando código JSX directamente en el contenido.

Por ejemplo, en un archivo .mdx podrías escribir:

import { Alert } from '../components/Alert'

# Bienvenida

Este es un fichero .mdx. Puedes ver mensajes como este:

<Alert type="info">Este es un componente React dentro del Markdown</Alert>

Los archivos .mdx son muy útiles en proyectos hechos con Astro, Next.js, Gatsby, entre otros, porque permiten enriquecer la documentación o los tutoriales con funcionalidad adicional.

3. Sintaxis básica

Markdown proporciona una serie de reglas simples para dar formato a los documentos. Estas reglas permiten definir títulos, listas, enlaces, imágenes, citas, bloques de código, entre otros.

3.1. Encabezados

Los encabezados en Markdown se crean utilizando el símbolo de almohadilla (#). La cantidad de almohadillas indica el nivel del encabezado:

# Título de nivel 1
## Título de nivel 2
### Título de nivel 3
#### Título de nivel 4
##### Título de nivel 5
###### Título de nivel 6

3.2. Párrafos y saltos de línea

En Markdown, un párrafo es simplemente un bloque de texto separado por una línea en blanco. No necesitas usar etiquetas ni comandos especiales para crear párrafos; Markdown los detecta automáticamente cuando dejas un espacio entre bloques de texto.

Esto es un primer párrafo.

Esto es un segundo párrafo.

Este código generará dos párrafos separados, ya que hay una línea en blanco entre ellos.

Para hacer un salto de línea sin iniciar un nuevo párrafo, puedes:

• Escribir dos espacios al final de la línea
• O bien usar una barra invertida al final: \\

Primera línea con salto de línea.
Segunda línea justo debajo.

Esto se mostrará como:

Primera línea con salto de línea.
Segunda línea justo debajo.

3.3. Énfasis: negrita y cursiva

Markdown permite resaltar partes del texto mediante cursiva y negrita, lo cual es muy útil para destacar ideas, palabras clave o instrucciones importantes.

• 🟡 Cursiva

Para escribir en cursiva, encierra el texto entre * o _:

*Este texto está en cursiva*
_Este también_

• ⚫ Negrita

Para usar negrita, se usan dobles asteriscos ** o guiones bajos __:

**Este texto está en negrita**
__Este también__

• 🟢 Combinación de negrita y cursiva

Puedes combinar ambos estilos añadiendo tres asteriscos *** o tres guiones bajosa ___:

___Este texto está en cursiva y negrita___
***Este texto está en cursiva y negrita***

3.4. Listas

Markdown permite crear dos tipos de listas: no ordenadas (con viñetas) y ordenadas (numeradas). Son una forma clara de organizar ideas, pasos o elementos relacionados.

• 🔹 Listas no ordenadas

Usa -, * o + seguidos de un espacio para crear una lista con viñetas.

- Manzana
- Pera
- Plátano

También puedes usar:

* Opción A
* Opción B

• 🔸 Listas ordenadas

Solo necesitas usar números seguidos de un punto y un espacio:

1. Paso uno
2. Paso dos
3. Paso tres

No importa si no están en orden (Markdown los mostrará correctamente), pero es buena práctica numerarlos bien.

3.5. Enlaces e imágenes

Markdown hace muy fácil añadir enlaces y mostrar imágenes sin tener que escribir código HTML.

• 🔗 Enlaces

La estructura básica es:

[Texto visible](https://url.com)

Por ejemplo:

Consulta el portal [FPCode](https://www.fpcode.es)

Esto se mostrará como:
👉 Consulta el portal FPCode

Se pueden hacer enlaces directamente con los simbolos < > sin incluir ningun texto alternativo.

Pulsa aquí 👉 <https://www.fpcode.es>

• 🖼️ Imágenes

Para insertar una imagen, se usa un signo de exclamación ! seguido del mismo formato que un enlace:

![Texto alternativo](https://url-de-la-imagen.com/imagen.png)

Por ejemplo:

![Logo de FPCode](https://www.fpcode.es/logo/entry.jpg)

Esto mostrará directamente la imagen (si está disponible desde esa URL).

3.6. Citas y bloques de código

Markdown te permite representar citas textuales y bloques de código, dos recursos muy útiles cuando estás escribiendo documentación técnica, explicando fragmentos de programación o resaltando información de una fuente externa.

• 🟨 Citas

Para escribir una cita o bloque citado, se utiliza el símbolo > al comienzo de la línea. Puedes usarlo para destacar frases, definiciones o citas de autores.

> Esta es una cita simple.

Esto se mostrará visualmente como:

Esta es una cita simple.

Puedes anidar varias líneas en una cita simplemente manteniendo el símbolo > en cada línea o añadiendo líneas en blanco dentro del bloque:

> Markdown permite escribir de forma simple.
>
> Esta es una segunda línea dentro de la misma cita.

• 🟥 Bloques de código

Markdown te permite mostrar fragmentos de código de dos formas:

Cuando necesitas mostrar solo una palabra o pequeña instrucción de código dentro de una frase, usa una sola ` para encerrar el fragmento:

El comando `npm install` se usa para instalar paquetes.

Esto se mostrará como:

El comando npm install se usa para instalar paquetes.

Cuando quieres mostrar varias líneas de código, utiliza tres ` seguidas al principio y al final del bloque. Puedes especificar el lenguaje después de las primeras tres ` para que tenga resaltado de sintaxis (esto es muy útil en editores como VSCode o plataformas como GitHub, Astro o Starlight).

Ejemplo para mostrar código html:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo</title>
  </head>
  <body>
    <p>Hola Markdown</p>
  </body>
</html>
`` `

Otro ejemplo para mostrar código javascript

```js
function saludar(nombre) {
  return "Hola, " + nombre + "!";
}
`` `

Esto permite que el código sea legible, esté bien formateado y no se mezcle con el texto normal del documento.

A continuación se muestra una lista cómun de lenguajes que puede soportar los bloques de código.

3.7. Reglas horizontales

Las reglas horizontales se utilizan para separar visualmente secciones dentro de un documento, creando una línea divisoria que ayuda a organizar el contenido.

Para crear una regla horizontal en Markdown, simplemente debes incluir en una línea vacía al menos tres de cualquiera de estos caracteres: asteriscos *, guiones - o guiones bajos _.

***
Sección 1
---
Sección 2
___

Estos símbolos se traducen en HTML como una etiqueta <hr>, que genera una línea horizontal en la presentación del contenido. Su visualización es:

Sección 1

Sección 2

4. Sintaxis avanzada

Aparte de los elementos básicos, Markdown ofrece características más avanzadas que permiten estructurar la información de forma más completa, como el uso de tablas, notas de pie de página, listas de definición, entre otros.. A parte, existe la posibilidad de insertar directamente código HTML. Esto facilita la combinación de Markdown con elementos HTML para personalizar aún más el contenido.

Es importante tener en cuenta que estas funcionalidades forman parte de una extensión de la sintaxis básica, lo que significa que no todas las aplicaciones o plataformas las soportan. Por ello, es recomendable comprobar si el entorno en el que trabajas admite estas características antes de usarlas.

4.1. Tablas

Markdown permite representar tablas de manera sencilla utilizando tuberías (|) y guiones (-). Las tablas son útiles para comparar elementos, mostrar datos estructurados o resumir características.

La estructura general de una tabla es:

| Columna 1 | Columna 2 |
|-----------|-----------|
| Dato A    | Dato B    |
| Dato C    | Dato D    |

Esto se verá así:

• 🧭 Alineación de columnas

Puedes alinear el contenido a la izquierda, al centro o a la derecha usando los dos puntos (:):

• Alineación a la izquierda: :---
• Alineación al centro: :---:
• Alineación a la derecha: ---:

Un ejemplo:

| Izquierda | Centro | Derecha |
|:----------|:------:|--------:|
| A         | B      | C       |
| D         | E      | F       |

4.2. Notas de pie de página

Las notas de pie de página son referencias dentro del texto que se desarrollan al final, muy útiles para citas o aclaraciones.

Este es un texto con una nota al pie.[^1]

[^1]: Esta es la explicación o aclaración de la nota.

4.3. Anclajes

Los IDs personalizados en los encabezados te permiten asignar un identificador único a cada título, lo que facilita enlazar directamente a esa sección desde cualquier lugar, ya sea dentro del mismo documento o desde otra página.

Esto es especialmente útil para crear índices dinámicos o referencias rápidas en documentos largos.

Ejemplo:

### Mi Gran Encabezado {#custom-id}

Después, puedes usar un enlace que apunte a ese ID así:

[Ir a Mi Gran Encabezado](#custom-id)

Así puedes enlazar directamente a ese título usando #custom-id en la URL o navegación.

4.4. Listas de definición

Sirven para definir términos de forma clara, muy usadas en glosarios.

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

Término 2
: Definición primera del término 2
: Definición segunda del término 2

Se mostrará:

Término 1

Definición del término 1

Término 2

Definición primera del término 2

Definición segunda del término 2

4.5. Listas de tareas

Permiten marcar tareas pendientes o completadas, muy usadas en gestión y seguimiento.

- [x] Escribir el comunicado de prensa
- [ ] Actualizar la página web
- [ ] Contactar con los medios

Ese código mostrará:

• Escribir el comunicado de prensa
• Actualizar la página web
• Contactar con los medios

4.6. Tachado

Para mostrar texto eliminado o corregido usando doble virgulilla.

~~El mundo es plano.~~

Eso mostrará:

El mundo es plano.

4.7. Emojis

Muchos sistemas permiten insertar emojis escribiendo su código entre dos puntos.

¡Eso es muy divertido! :joy:

Así se podrá ver los iconos:

¡Eso es muy divertido! 😄

4.8. Resaltado

Algunas implementaciones permiten destacar texto con doble signo igual.

Necesito resaltar estas ==palabras muy importantes==.

Se verá así:

Necesito resaltar estas palabras muy importantes.

4.9. Subíndice y superíndice

Se usa para escribir texto en formato subíndice o superíndice, común en fórmulas químicas o matemáticas, como potencias o exponentes.

H~2~O

Mostrará: H₂O

X^2^

Mostrará: X²

4.10. Markdown + HTML

Una de las ventajas de Markdown es que permite insertar código HTML directamente dentro del documento, lo cual resulta muy útil cuando necesitas una personalización que Markdown no cubre por sí solo. Además, al usar etiquetas HTML puedes aplicar estilos CSS en línea para modificar la apariencia del contenido de forma más detallada.

El resultado será un texto estilizado con color y negrita, sin haber utilizado sintaxis Markdown para aplicar formato, sino directamente CSS mediante atributos HTML.

También es posible combinar contenido escrito en Markdown con estructuras HTML más complejas, como listas o tablas personalizadas:

<p style="color: teal; font-weight: bold;">
Este texto usa HTML dentro de Markdown.
</p>

Esta combinación te da un mayor control visual respecto a las listas tradicionales de Markdown. Es especialmente útil cuando necesitas añadir atributos, aplicar clases CSS o integrar elementos interactivos en un sitio web o documentación enriquecida.

Esto es un ejemplo, combinando *Markdown* y **HTML**.
<ul>
  <li>Elemento A</li>
  <li>Elemento B</li>
  <li>Elemento C</li>
</ul>

Esto permite un mayor control visual que las listas tradicionales en Markdown, por ejemplo si quieres aplicar clases, estilos o atributos específicos.

5. Herramientas para trabajar con Markdown

Para trabajar con Markdown no basta con tener un editor de texto: es necesario también contar con herramientas que traduzcan o compilen el contenido Markdown a HTML u otros formatos utilizables en la web o documentos. Afortunadamente, existe un amplio ecosistema de editores, procesadores y convertidores que facilitan esta tarea y mejoran la experiencia de escritura y publicación.

A continuación, se describen algunas de las herramientas más utilizadas.

Editores de Markdown

• Visual Studio Code es un editor generalista, y permite trabajar con Markdown ampliando su funcionalidad con las extensiones que se le pueden instalar, como MDX para manejar archivos .mdx o markdownlint para mantener la sintaxis correcta y consistente. VS Code ofrece funcionalidades avanzadas como autocompletado, vista previa en tiempo real, resaltado de sintaxis, y manejo de snippets, lo que lo convierte en un entorno muy potente y personalizable para crear documentos Markdown o contenido MDX dentro de proyectos web.

• Dilliger es un editor Markdown online y gratuito, ideal para quienes prefieren no instalar software. Permite escribir, editar y exportar documentos Markdown directamente desde el navegador, con integración a servicios en la nube como Dropbox, GitHub y Google Drive. Es perfecto para trabajos rápidos, colaborativos o cuando se trabaja desde diferentes dispositivos sin un entorno fijo.

• Obsidian, editor centrado en la toma de notas y la organización del conocimiento basadas en Markdown, con un enfoque en la creación de redes de conocimiento mediante enlaces entre notas. Su principal ventaja es la posibilidad de crear redes de notas enlazadas, lo que facilita la gestión de documentación compleja o extensa. Es especialmente útil para escritores, investigadores y profesionales que trabajan con grandes volúmenes de información y necesitan mantenerla estructurada y fácilmente accesible.

Convertidores y procesadores

Además de los editores, es imprescindible contar con herramientas que conviertan el Markdown a HTML o a otros formatos útiles para su publicación y distribución.

• Pandoc es una herramienta extremadamente versátil que funciona como un convertidor universal de documentos. Soporta múltiples formatos de entrada y salida, incluyendo Markdown, HTML, PDF, LaTeX, DOCX, EPUB y muchos más. Esto permite, por ejemplo, generar documentos profesionales a partir de archivos Markdown, o integrar Markdown en flujos de trabajo académicos o editoriales complejos. Pandoc también soporta extensiones de Markdown avanzado y permite personalizar el resultado final mediante plantillas y filtros.

6. Ejercicios