Convertidor online gratuito de ASCIIDOC a MD

GitHub, GitLab y muchas herramientas de documentación aceptan Markdown, pero no AsciiDoc, por lo que un archivo .adoc puede necesitar una conversión antes de publicarlo o editarlo allí. Convertirlo a .md conserva el código fuente legible y adapta los encabezados, las listas, los enlaces y los bloques de código a la sintaxis de Markdown.

Qué es el formato ASCIIDOC

AsciiDoc es un formato de marcado de texto plano utilizado para documentación de software, manuales, libros, notas de versión y archivos README. Las extensiones comunes incluyen .adoc, .asciidoc y .ad.

Los archivos AsciiDoc suelen crearse o procesarse con Asciidoctor, la implementación moderna en Ruby, o con el procesador AsciiDoc antiguo. Los editores como Visual Studio Code, IntelliJ IDEA y las herramientas de documentación especializadas también pueden crear estos archivos, ya que el código fuente es texto ordinario.

AsciiDoc admite atributos, directivas include, bloques de admonición, tablas, referencias cruzadas, diagramas, citas y estructuras de documentos reutilizables. Algunas de estas funciones no tienen un equivalente directo en Markdown.

Qué es el formato MD

MD es la extensión habitual para los archivos Markdown. Markdown es texto plano ligero diseñado para que el código fuente sea legible y se pueda representar fácilmente como HTML. GitHub, GitLab, Bitbucket, los generadores de sitios estáticos, las wikis, las aplicaciones para tomar notas y los editores de código suelen admitirlo.

Markdown es un destino práctico cuando un repositorio requiere un README.md, cuando los colaboradores editan la documentación con herramientas orientadas a Markdown o cuando los archivos fuente deben mostrarse de manera uniforme en distintas plataformas de alojamiento de código. GitHub Flavored Markdown (GFM) añade tablas, listas de tareas, autovínculos y bloques de código delimitados.

Cómo convertir realmente ASCIIDOC a MD

Para realizar una conversión local, instala Pandoc y ejecuta:

pandoc input.adoc -f asciidoc -t gfm -o output.md

Reemplaza input.adoc por el nombre del archivo fuente y output.md por el destino deseado. La opción -f asciidoc selecciona el lector de AsciiDoc, -t gfm produce GitHub Flavored Markdown y -o escribe el resultado en un archivo.

Para convertir un archivo con la extensión .asciidoc, utiliza su nombre real:

pandoc manual.asciidoc -f asciidoc -t gfm -o manual.md

Si la versión instalada de Pandoc no proporciona un lector de AsciiDoc, utiliza Asciidoctor para crear primero DocBook XML y luego convierte ese archivo intermedio:

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc intermediate.xml -f docbook -t gfm -o output.md

Como opción sin instalación, sube el archivo fuente a 101convert.com, elige Markdown como formato de salida, inicia la conversión y descarga el archivo .md resultante. Evita subir documentos que contengan información confidencial o restringida.

Limitaciones de calidad y compatibilidad

La conversión no siempre es sin pérdida. Los atributos de AsciiDoc, el contenido condicional, los includes, los roles personalizados, las macros, las extensiones, las tablas complejas, las admoniciones y las referencias cruzadas pueden simplificarse, omitirse o generarse como marcado sin procesar.

Inspecciona el Markdown generado para comprobar los niveles de los encabezados, la anidación de las listas, el formato de las tablas, las rutas de las imágenes, los bloques de código, los enlaces y los caracteres escapados. GFM admite tablas y listas de tareas, pero otros analizadores de Markdown pueden representar esas funciones de manera diferente.

Los includes de AsciiDoc pueden requerir un preprocesamiento antes de la conversión. Resuelve los archivos referenciados por las directivas include:: y comprueba que las rutas relativas de las imágenes y los enlaces sigan apuntando a las ubicaciones correctas después de mover el archivo de salida.