Markdown vs AsciiDoc

Comparativa entre Markdown y AsciiDoc para documentación técnica. Diferencias de sintaxis, funciones exclusivas de AsciiDoc, herramientas y cuándo elegir cada uno.

Markdown y AsciiDoc son dos lenguajes de marcado ligero populares en el mundo de la documentación técnica. Aunque comparten el objetivo de simplificar la escritura, AsciiDoc ofrece funcionalidades más avanzadas que Markdown a costa de una mayor complejidad.

Qué es AsciiDoc

AsciiDoc es un lenguaje de marcado ligero pensado desde el principio para escribir documentación técnica, manuales y libros. Igual que Markdown, se escribe en texto plano y se convierte a HTML, PDF u otros formatos, pero su sintaxis cubre de serie muchas cosas que en Markdown dependen de extensiones: notas y advertencias, inclusión de archivos, variables, índices automáticos o tablas complejas.

La diferencia de fondo está en el diseño. Markdown nació para escribir texto para la web de la forma más sencilla posible, y por eso existen tantas variantes que añaden funciones por su cuenta, como explicamos en versiones de Markdown. AsciiDoc, en cambio, tiene una sintaxis más amplia y una implementación de referencia, Asciidoctor, que hace que un documento se procese igual en todas partes.

Comparativa rápida

La siguiente tabla resume las diferencias más importantes entre los dos lenguajes:

CaracterísticaMarkdownAsciiDoc
Curva de aprendizajeMuy fácilModerada
SintaxisSimpleMás compleja
TablasBásicasAvanzadas
Notas y advertenciasNo nativoNativo
Inclusión de archivosNoSí
Tabla de contenidosCon extensionesNativo
Variables (atributos)NoSí
AdopciónMuy altaModerada
HerramientasMuchasMenos, pero potentes

Sintaxis lado a lado

La mayoría de elementos básicos existen en los dos lenguajes, pero con marcas distintas. Esta tabla compara la sintaxis más habitual; tienes la de Markdown explicada en detalle en la guía de sintaxis básica y en la de sintaxis extendida.

ElementoMarkdownAsciiDoc
Título del documento# Título= Título
Encabezado de sección## Sección== Sección
Negrita**texto***texto*
Cursiva*texto*_texto_
Código en línea`codigo``codigo`
Enlace[texto](https://ejemplo.com)https://ejemplo.com[texto]
Imagen![alt](imagen.png)image::imagen.png[alt]
Lista con viñetas- elemento* elemento
Lista numerada1. elemento. elemento
NotaNo estándarNOTE: texto
Incluir otro archivoNo existeinclude::archivo.adoc[]

Fíjate en la negrita y la cursiva: en AsciiDoc un solo asterisco es negrita, mientras que en Markdown es cursiva. Es la confusión más habitual al pasar de un lenguaje a otro.

Ejemplo de comparación

Este es el mismo fragmento escrito en los dos lenguajes, con un título, una nota y una tabla.

En Markdown

En Markdown, la nota se suele simular con una cita y una negrita:

# Titulo

> **Nota**: Esto es una nota importante.

| Columna 1 | Columna 2 |
|---|---|
| Dato 1 | Dato 2 |

En AsciiDoc

En AsciiDoc, la nota es un elemento propio del lenguaje y la tabla se delimita con |===:

= Titulo

NOTE: Esto es una nota importante.

|===
| Columna 1 | Columna 2

| Dato 1
| Dato 2
|===

Lo que AsciiDoc tiene y Markdown no

Estas funciones son las que hacen que muchos equipos de documentación elijan AsciiDoc. Todas forman parte del lenguaje, sin depender de extensiones.

Admoniciones

AsciiDoc tiene cinco tipos de avisos nativos: NOTE, TIP, IMPORTANT, CAUTION y WARNING. Se pueden escribir en una sola línea o como bloque, cuando el aviso ocupa varios párrafos:

WARNING: Haz una copia de seguridad antes de actualizar.

[IMPORTANT]
====
Este bloque puede contener varios parrafos,
listas o incluso codigo.
====

En Markdown no hay un equivalente estándar, aunque GitHub y otras plataformas tienen su propia sintaxis de alertas. Lo explicamos en cómo mostrar advertencias en Markdown.

Inclusión de archivos

La directiva include inserta el contenido de otro archivo en el punto donde se escribe. Permite dividir un manual largo en capítulos o reutilizar el mismo fragmento en varios documentos. Además, se puede incluir solo un rango de líneas o una región marcada, algo muy útil para mostrar trozos de código fuente real:

include::capitulos/instalacion.adoc[]

include::src/main.py[lines=10..25]

Atributos

Los atributos son variables que se definen una vez y se reutilizan en todo el documento. Si cambia la versión de un producto, se actualiza en un solo sitio:

:version: 2.4
:producto: MiApp

Para instalar {producto} {version}, ejecuta el instalador.

Los atributos también activan funciones del documento, como :toc:, que genera la tabla de contenidos automáticamente.

Tablas complejas y referencias cruzadas

Las tablas de AsciiDoc admiten celdas que ocupan varias filas o columnas, anchos de columna, alineación y contenido con formato dentro de cada celda. En Markdown las tablas son mucho más limitadas, como vemos en cómo formatear tablas.

Las referencias cruzadas enlazan con cualquier sección del documento por su identificador, y el procesador mantiene el enlace aunque cambie el título. En documentos de cientos de páginas, esto evita enlaces rotos.

Ventajas de Markdown sobre AsciiDoc

Markdown sigue siendo la opción más extendida por varios motivos:

  • Simplicidad: es más fácil de aprender y recordar.
  • Adopción masiva: GitHub, GitLab, Stack Overflow, Discord, Slack y casi cualquier herramienta de notas.
  • Más herramientas: tiene un ecosistema mucho mayor de editores, procesadores y generadores de sitios.
  • Más gente lo conoce: hay menos barrera para que otras personas contribuyan a la documentación.
  • Es el formato de la IA: los chatbots y agentes de IA leen y escriben Markdown de forma nativa.

Herramientas para AsciiDoc

El ecosistema de AsciiDoc es más pequeño, pero está muy centrado en la documentación técnica. Estas son las piezas principales:

  • Asciidoctor: el procesador de referencia, que convierte AsciiDoc a HTML, PDF, EPUB y otros formatos. Tiene versiones para Ruby, Java y JavaScript.
  • Antora: un generador de sitios estáticos que convierte documentación AsciiDoc guardada en repositorios Git en un sitio web completo, siguiendo la filosofía de documentación como código.
  • GitHub y GitLab: muestran los archivos .adoc renderizados directamente en el repositorio, igual que hacen con los .md, aunque no admiten todas las funciones del procesador completo.
  • Editores: VS Code y los IDE de JetBrains tienen extensiones con vista previa de AsciiDoc.

Si necesitas pasar documentación de Markdown a AsciiDoc, Pandoc hace la conversión. En sentido contrario hay que tener en cuenta que las funciones exclusivas de AsciiDoc no tienen equivalente en Markdown y se pierden por el camino.

Cuándo usar cada uno

La elección depende sobre todo del tamaño de la documentación y de quién va a escribirla:

SituaciónMejor opción
README de proyectoMarkdown
Documentación técnica extensaAsciiDoc
BlogMarkdown
Libro técnicoAsciiDoc
WikisMarkdown
Manuales de productoAsciiDoc
Documentación con muchos colaboradores ocasionalesMarkdown
Contenido que procesará una IAMarkdown

Si estás montando la documentación de un producto, en documentación técnica con Markdown tienes un flujo de trabajo completo. Y si tu caso es académico o científico, la comparativa que te interesa es Markdown vs LaTeX.

Conclusión

Markdown es mejor para contenido corto y plataformas sociales o colaborativas. AsciiDoc es más adecuado para documentación técnica extensa que requiere funcionalidades avanzadas, como avisos, inclusión de archivos o variables. Si Markdown se queda corto para tus necesidades, AsciiDoc es el siguiente paso natural.

👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.

para estar al día con mi contenido. 😊