Formato Markdown: Archivos .md Explicados

Markdown: Guía Completa del Formato .md

En 2004, John Gruber y Aaron Swartz crearon Markdown con un objetivo simple: permitir que las personas escriban usando texto plano que sea fácil de leer y fácil de convertir a HTML. Dos décadas después, Markdown se ha convertido en el formato dominante para documentación técnica, archivos README, blogs, toma de notas y escritura online — usado en GitHub, Stack Overflow, Reddit, Discord, Notion, Obsidian y cientos de otras plataformas.

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero que usa caracteres de puntuación simples para indicar el formato. Un archivo Markdown tiene la extensión .md (a veces .markdown). Su genialidad es que ya es legible como texto plano — los caracteres de formato son intuitivos:

# Este es un título

Este es un párrafo con **texto en negrita**, *texto en cursiva* y `código en línea`.

- Primer elemento de lista
- Segundo elemento de lista

1. Elemento ordenado uno
2. Elemento ordenado dos

[Visitar GitHub](https://github.com)

![Texto alternativo de imagen](imagen.jpg)

> Este es un bloque de cita

| Columna 1 | Columna 2 |
|-----------|-----------|
| Celda 1   | Celda 2   |

Sintaxis Básica de Markdown

Títulos

# H1 — Título de página o documento
## H2 — Sección principal
### H3 — Subsección
#### H4 — Sub-subsección

Énfasis

**texto en negrita** o __texto en negrita__
*texto en cursiva* o _texto en cursiva_
***negrita y cursiva***
~~tachado~~

Código

`código en línea` — comillas simples inversas para código en línea

```python
# Bloque de código vallado con especificador de lenguaje
def hola():
    print("Hola, Markdown!")
```

Tablas (extensión GFM)

| Cabecera 1 | Cabecera 2 | Cabecera 3 |
|------------|:----------:|-----------:|
| Izquierda  | Centrado   | Derecha    |

Variantes de Markdown y Especificaciones

No existe un único estándar de Markdown. Esto ha llevado a una proliferación de variantes:

CommonMark: una especificación estricta y sin ambigüedades (commonmark.org, 2014). Define cómo debe manejarse cada caso límite.

GitHub Flavored Markdown (GFM): CommonMark más tablas, listas de tareas, tachado, autoenlaces y bloques de código vallados con resaltado de sintaxis.

Pandoc Markdown: el dialecto extendido de Pandoc con notas al pie, citas, bloques de metadatos YAML, tablas de cuadrícula y listas de definición.

R Markdown (.Rmd): Markdown + fragmentos de código R incrustados que se ejecutan al renderizarse. Usado en ciencia de datos.

MDX: Markdown + componentes React JSX. Usado en sitios de documentación modernos.

Conversión de Markdown

Markdown → HTML: todas las bibliotecas Markdown hacen esto — Marked.js (JavaScript), Python-Markdown.

Markdown → PDF: usa Pandoc: pandoc entrada.md -o salida.pdf

Markdown → Word (.docx): pandoc entrada.md -o salida.docx — produce un documento Word correctamente estructurado con estilos

Markdown → Diapositivas: Marp, Reveal.js o Pandoc con --to revealjs

HTML → Markdown: Pandoc: pandoc -f html -t markdown entrada.html -o salida.md

Word → Markdown: pandoc entrada.docx -t markdown -o salida.md

Markdown en Generadores de Sitios Estáticos

Markdown es el formato de contenido principal para casi todos los generadores de sitios estáticos:

Jekyll (GitHub Pages por defecto): procesa archivos .md con YAML front matter
Hugo: procesador Markdown excepcionalmente rápido
MkDocs: sitios de documentación con Markdown como base
Docusaurus: el framework de documentación de Facebook, basado en MDX

El flujo de trabajo del generador de sitios estáticos: escribe contenido en archivos .md → el generador procesa Markdown → produce HTML/CSS/JS estático → despliega en CDN.

Markdown para Archivos README

El archivo README.md en un repositorio de GitHub es la cara de los proyectos de código abierto. Mejores prácticas:

Comienza con una descripción clara del proyecto e insignias (estado de construcción, licencia, versión)
Instrucciones de instalación con bloques de código que se puedan copiar y pegar
Ejemplo de inicio rápido con un bloque de código
Lista de características
Enlace a la documentación completa
Directrices de contribución y licencia

La simplicidad de Markdown — legible como texto plano, se renderiza de forma atractiva en los navegadores — lo hace el formato perfecto para la documentación que vive junto al código en el control de versiones.

Conversiones relacionadas

Conversiones de documento que siguen este tema:

Preguntas frecuentes

Markdown es un lenguaje de marcado ligero que usa puntuación simple para indicar el formato — `**negrita**`, `*cursiva*`, `# Título`, `[enlace](url)`. Un archivo .md (o .markdown) es un archivo de texto plano escrito en sintaxis Markdown. Es legible tal cual en cualquier editor de texto, y puede renderizarse a HTML con estilo por cualquier procesador Markdown. GitHub, Notion, Obsidian, Reddit, Discord, Stack Overflow y cientos de otras plataformas renderizan Markdown.

Envía <strong>PDF</strong> cuando el documento es final y el layout debe preservarse tal cual (contratos, facturas, certificados). Envía <strong>DOCX</strong> cuando los revisores deben editar, comentar o usar control de cambios. Muchos equipos envían ambos: PDF como versión canónica + DOCX para feedback editable. PDF/A es el adecuado para archivado legal (ISO 19005).

La especificación original de Markdown de John Gruber (2004) dejó muchos casos límite ambiguos, por lo que diferentes plataformas crearon sus propias variantes. CommonMark (2014) es una especificación estricta y sin ambigüedades — el mejor "estándar" de Markdown. GitHub Flavored Markdown (GFM) es CommonMark más tablas, listas de tareas (`- [x]`), tachado y bloques de código vallados con resaltado de sintaxis. Pandoc Markdown es el más potente: añade notas al pie, citas, metadatos YAML y listas de definición.

Round-trip entre formatos similares (DOCX ↔ ODT, DOCX → PDF) suele ser seguro. Round-trip con funciones específicas del formato (macros de Word, tablas complejas, notas al pie) suele perder fidelidad. Las fuentes incrustadas sobreviven solo si origen y destino lo soportan (PDF sí, DOCX sí, HTML plano no). Previsualiza siempre antes de borrar el original.

La herramienta más potente es Pandoc (pandoc.org, gratuito): `pandoc entrada.md -o salida.pdf`. Pandoc requiere un motor LaTeX (instala TeX Live o MiKTeX) para la salida PDF; alternativamente usa `--pdf-engine=wkhtmltopdf` para la conversión HTML-a-PDF que no requiere LaTeX. Para una opción más simple, VS Code con la extensión "Markdown PDF" convierte .md a PDF directamente.

Si el PDF contiene texto real (no imágenes escaneadas), <code>pdftotext</code> de poppler-utils o <a href="/es/convert/pdf-a-txt">PDF a TXT</a> funcionan en segundos. Si el PDF es escaneado, necesitas OCR — Tesseract es el estándar open-source. Las herramientas PDF de KaijuConverter detectan automáticamente texto vs. imagen y enrutan según el caso.

Sí, con Pandoc: `pandoc entrada.docx -t markdown -o salida.md`. Pandoc convierte títulos, negrita/cursiva, listas, tablas e imágenes con fidelidad razonable. El resultado necesitará algo de limpieza — especialmente para el formato complejo de Word como cambios registrados, cuadros de texto y estilos personalizados que no tienen equivalente en Markdown. Para el proceso inverso (Markdown a Word): `pandoc entrada.md -o salida.docx` produce un documento Word correctamente estructurado con estilos de título.

Edición ligera (anotaciones, firmas, campos de formulario) es viable en cualquier lector PDF. Edición estructural (cambiar párrafos, reemplazar imágenes) es incómoda — PDF es un formato de presentación, no de edición. El flujo robusto es: mantén el origen DOCX/MD/HTML como máster y regenera el PDF cuando haya cambios. Las herramientas que "editan PDF" hacen ingeniería inversa del layout y suelen romperlo.