Convertidor online gratuito de ASCIIDOC a HTML

Los archivos AsciiDoc necesitan conversión cuando la documentación debe abrirse en un navegador web, publicarse en un sitio web o proporcionarse a un sistema que acepte HTML en lugar del código fuente de marcado. HTML conserva los encabezados, las listas, los enlaces, las tablas, los bloques de código y otras estructuras en un formato que se puede visualizar directamente.

Qué es el formato ASCIIDOC

AsciiDoc es un formato de marcado de texto plano para documentos estructurados, como documentación de software, manuales, archivos README, artículos y especificaciones técnicas. Los autores indican la estructura mediante una sintaxis legible para encabezados, listas, enlaces, advertencias, tablas, código fuente, imágenes y referencias cruzadas.

Las extensiones de archivo comunes son .adoc, .asciidoc y, en ocasiones, .asc. Los archivos se crean o editan con editores de texto comunes y herramientas de documentación, como Asciidoctor, Asciidoctor.js y Antora. Un archivo AsciiDoc es código fuente de marcado, por lo que un navegador mostrará sus caracteres de formato en lugar de representar la estructura prevista del documento.

Qué es el formato HTML

HTML es el formato de marcado interpretado por los navegadores web y utilizado por sitios web, portales de documentación, sistemas de gestión de contenido y flujos de trabajo relacionados con el correo electrónico. Una conversión a HTML transforma la estructura de AsciiDoc en elementos como <h1>, <p>, <ul>, <table> y <pre>.

HTML es adecuado cuando los destinatarios necesitan visualizar la documentación en un navegador, buscar en ella, copiar su contenido o disponer de un archivo que pueda insertarse en una página web. El resultado puede incluir estilos CSS, referencias a imágenes, recursos para el resaltado de sintaxis y enlaces a otras páginas generadas.

Cómo convertir realmente ASCIIDOC a HTML

Uso de Asciidoctor

1. Instala Ruby y el procesador Asciidoctor; después, ejecuta gem install asciidoctor.
2. Abre un terminal en el directorio que contiene el archivo de origen.
3. Conviértelo con asciidoctor input.adoc -o output.html. Sustituye los nombres de archivo por los nombres reales del origen y del destino.
4. Abre output.html en un navegador y comprueba los encabezados, enlaces, tablas, bloques de código e imágenes.

Para generar HTML incrustado adecuado para insertarlo en otra página, utiliza asciidoctor -e input.adoc -o fragment.html. Para aplicar una hoja de estilos, proporciona su ubicación mediante un atributo de Asciidoctor, como asciidoctor -a stylesheet=site.css input.adoc -o output.html.

Uso de un convertidor en línea

Puedes convertir el archivo de forma gratuita en el sitio web 101convert.com sin instalar software. Sube el archivo AsciiDoc, selecciona HTML como formato de salida si es necesario, inicia la conversión y descarga el archivo generado. Revisa las imágenes vinculadas y los archivos incluidos después de la descarga, ya que la conversión basada en el navegador puede no tener acceso a las rutas locales a las que hace referencia el código fuente.

Consideraciones sobre calidad y compatibilidad

Los documentos AsciiDoc pueden hacer referencia a imágenes, incluir otros archivos de origen, cargar atributos y utilizar extensiones personalizadas. Normalmente, es preferible realizar una conversión local con Asciidoctor cuando esas dependencias son importantes, ya que el convertidor puede ejecutarse desde el directorio correcto del proyecto y utilizar los atributos previstos.

Mantén las imágenes referenciadas y los archivos CSS en sus ubicaciones relativas previstas o actualiza las rutas generadas antes de publicar. Un archivo HTML puede contener enlaces a recursos independientes en lugar de incrustarlos, por lo que mover únicamente el archivo HTML puede provocar que falten imágenes o que el resultado no tenga estilos.

Las macros personalizadas, las extensiones no compatibles, los includes que faltan y los atributos de documento incorrectos pueden producir un resultado incompleto. Prueba el HTML generado en el navegador o sistema de publicación de destino, especialmente cuando el código fuente utiliza resaltado de sintaxis, enlaces entre documentos o caracteres no ASCII.