¿Qué es Markdown?
Markdown es un lenguaje de marcado ligero creado por John Gruber y Aaron Swartz en 2004, diseñado para ser legible como texto plano mientras también se convierte limpiamente a HTML. La filosofía principal: la fuente debe verse bien como texto plano, no estar atestada de etiquetas. Un archivo .md o .markdown es texto plano que cualquier editor de texto puede abrir, pero que las herramientas de renderizado convierten a HTML formateado, PDF, DOCX u otros formatos.
Markdown es ahora omnipresente en la escritura técnica:
- GitHub, GitLab, Bitbucket: Todos los archivos README, wikis y comentarios de issues usan Markdown
- Generadores de sitios estáticos: Jekyll, Hugo, Gatsby, Astro usan Markdown para contenido
- Plataformas de documentación: ReadTheDocs, GitBook, Docusaurus, MkDocs
- Aplicaciones de notas: Obsidian, Logseq, Notion, Bear, iA Writer
Sintaxis de Markdown
Encabezados
# Encabezado 1 (H1) — un signo #
## Encabezado 2 (H2) — dos signos #
### Encabezado 3 (H3)
#### Encabezado 4 (H4)
Énfasis
**Texto en negrita** o __negrita__
*Texto en cursiva* o _cursiva_
***Negrita y cursiva***
~~Tachado~~ (extensión GFM)
`Código en línea` — monoespaciado, sin procesamiento
Listas
Lista sin ordenar:
- Elemento uno
- Elemento dos
- Elemento anidado (2 espacios o sangría de tabulador)
- Elemento tres
Lista ordenada:
1. Primer elemento
2. Segundo elemento
3. Tercer elemento
Enlaces e Imágenes
[Texto del enlace](https://ejemplo.com)
[Enlace con título](https://ejemplo.com "Texto de información emergente")
Autoenlaces: <https://ejemplo.com>
Bloques de Cita y Código
> Esto es una cita en bloque.
> Puede abarcar múltiples líneas.
>> Cita en bloque anidada
Bloque de código delimitado (especifica el lenguaje para resaltado de sintaxis):
```python
def hola(nombre):
return f"Hola, {nombre}!"
## Variantes y Especificaciones de Markdown
La especificación original de Markdown (2004) estaba poco definida, lo que llevó a implementaciones inconsistentes. Surgieron varios esfuerzos de estandarización:
### CommonMark
Una especificación estricta e inequívoca que resuelve las ambigüedades en la especificación original de Gruber. Usado por GitHub (como base para GFM), Reddit, Stack Overflow.
### GFM (GitHub Flavored Markdown)
Un superconjunto de CommonMark con extensiones específicas de GitHub:
- **Tablas** (sintaxis de barras verticales)
- **Listas de tareas** (casillas de verificación)
- **Tachado** (`~~texto~~`)
- **Autoenlaces** (las URLs desnudas se convierten en enlaces)
### Tablas GFM
```markdown
| Columna 1 | Columna 2 | Columna 3 |
|-----------|:---------:|----------:|
| Izquierda | Centro | Derecha |
| Alineado | Alineado | Alineado |
Listas de Tareas GFM
- [x] Tarea completada
- [x] Otro elemento hecho
- [ ] Tarea pendiente
- [ ] Otro elemento por hacer
Frontmatter YAML
Muchos procesadores de Markdown admiten frontmatter YAML — metadatos estructurados al principio de un archivo entre delimitadores ---:
---
título: "Mi Documento"
autor: "Juan García"
fecha: 2025-03-15
etiquetas: [programación, documentación]
borrador: false
---
# Primer Encabezado
El contenido del documento comienza aquí...
Conversión de Markdown
Pandoc — El Convertidor Universal
# Markdown a HTML
pandoc entrada.md -o salida.html
# Markdown a HTML autónomo (con CSS)
pandoc -s entrada.md -o salida.html --css estilos.css
# Markdown a PDF (requiere LaTeX)
pandoc entrada.md -o salida.pdf
# Markdown a DOCX
pandoc entrada.md -o salida.docx
# Markdown a EPUB
pandoc entrada.md -o salida.epub --epub-cover-image=portada.jpg
# Múltiples archivos Markdown concatenados
pandoc capitulo1.md capitulo2.md capitulo3.md -o libro.pdf
Python
import markdown
with open('entrada.md') as f:
texto = f.read()
html = markdown.markdown(texto, extensions=[
'tables',
'fenced_code',
'codehilite',
'toc',
'footnotes',
])
print(html)
Markdown vs Otros Lenguajes de Marcado Ligero
| Característica | Markdown | reStructuredText (RST) | AsciiDoc | Org-mode |
|---|---|---|---|---|
| Curva de aprendizaje | La más baja | Media | Media | Alta |
| Soporte matemático | Via MathJax/KaTeX | Decente | Bueno | Excelente |
| Referencias cruzadas | Limitadas | Completas (roles RST) | Completas | Completas |
| Destinos de salida | HTML, PDF, DOCX | HTML, PDF, EPUB | HTML, PDF, EPUB | HTML, PDF, LaTeX |
| Uso principal | Docs dev, GitHub | Docs Python (Sphinx) | Libros técnicos | Usuarios avanzados Emacs |
Mejores Prácticas de Markdown
Para documentación:
- Usa encabezados ATX (
#) en lugar de encabezados Setext - Mantén las líneas en menos de 100 caracteres (diffs más fáciles en control de versiones)
- Siempre añade texto alternativo a las imágenes
- Usa un linter (markdownlint) en pipelines de CI
Para mantenibilidad:
- Valida el esquema de frontmatter (linting YAML)
- Fija la versión de Pandoc/remark para evitar cambios de comportamiento
- Almacena las imágenes cerca de los archivos Markdown que las referencian (rutas relativas)
El atractivo duradero de Markdown radica en su equilibrio: suficiente estructura para habilitar la automatización, suficiente simplicidad para permanecer legible como código fuente. Ese equilibrio lo ha convertido en el estándar de facto para la documentación orientada a desarrolladores en un tiempo notablemente corto.
Conversiones relacionadas
Conversiones de documento que siguen este tema: