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.
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.
La siguiente tabla resume las diferencias más importantes entre los dos lenguajes:
| Característica | Markdown | AsciiDoc |
|---|---|---|
| Curva de aprendizaje | Muy fácil | Moderada |
| Sintaxis | Simple | Más compleja |
| Tablas | Básicas | Avanzadas |
| Notas y advertencias | No nativo | Nativo |
| Inclusión de archivos | No | Sí |
| Tabla de contenidos | Con extensiones | Nativo |
| Variables (atributos) | No | Sí |
| Adopción | Muy alta | Moderada |
| Herramientas | Muchas | Menos, pero potentes |
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.
| Elemento | Markdown | AsciiDoc |
|---|---|---|
| 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 |  | image::imagen.png[alt] |
| Lista con viñetas | - elemento | * elemento |
| Lista numerada | 1. elemento | . elemento |
| Nota | No estándar | NOTE: texto |
| Incluir otro archivo | No existe | include::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.
Este es el mismo fragmento escrito en los dos lenguajes, con un título, una nota y una tabla.
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, 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
|===Estas funciones son las que hacen que muchos equipos de documentación elijan AsciiDoc. Todas forman parte del lenguaje, sin depender de extensiones.
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.
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]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.
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.
Markdown sigue siendo la opción más extendida por varios motivos:
El ecosistema de AsciiDoc es más pequeño, pero está muy centrado en la documentación técnica. Estas son las piezas principales:
.adoc renderizados directamente en el repositorio, igual que hacen con los .md, aunque no admiten todas las funciones del procesador completo.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.
La elección depende sobre todo del tamaño de la documentación y de quién va a escribirla:
| Situación | Mejor opción |
|---|---|
| README de proyecto | Markdown |
| Documentación técnica extensa | AsciiDoc |
| Blog | Markdown |
| Libro técnico | AsciiDoc |
| Wikis | Markdown |
| Manuales de producto | AsciiDoc |
| Documentación con muchos colaboradores ocasionales | Markdown |
| Contenido que procesará una IA | Markdown |
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.
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.
Sígueme en Twitter para estar al día con mi contenido. 😊