| | Aunque todo el ecosistema de Asciidoctor funciona también en Windows yo no lo uso, así que en esta entrada todo lo que explique sobre instalación, ejemplos y demás será bajo Linux |

Ecosistema

Asciidoc es un formato para documentos de texto usado para escribir notas, articulos, libros, páginas web, manpages, blogs, presentaciones orientado a su transformación en html, pdf, epub, etc (http://asciidoc.org )

Con esta definición lo primero que pensarás es que es otroMarkdown y que para eso ya te quedas con este que es muy usado y lo soporta Github. Sin embargo, aunque ambos, como algún otro, están orientados a documentar en texto plano lasdiferencias son enormes.^[1]

Se podría decir queAsciidoc define las reglas sintácticas sobre los elementos del documento pues especifica dónde va el título, el autor, los párrafos, etc

| | Si te suena o has usadoreStructuredText entonces puedes ver aasciidoc como otra alternativa a este. |

Asciidoctor (https://asciidoctor.org) es unaimplementación , un programa, un ejecutable, que es capaz de leer documentosasciidoc y conventirlos a html5, docbook, pdf, etc. Como ves son parecidos, e incluso confusos, pero son dos cosas diferentes: uno podríamos verlo como las especificaciones y al otro como un traductor

| | Para complicar más la cosa, existe una implementación llamadaasciidoc , igual que las especificaciones, pero que su última actualización es del 2013. Así, cuando en este documento hable deasciidoc estaré hablando de las especificaciones y no de esta implementación. |

La implementaciónasciidoctor está desarrollada en Ruby pero existen otras implementaciones como:

• asciidoctorJ, un jar de java que puedes ejecutar desde la línea de comando o integrarlo en tu aplicación

• asciidoctor-js, un paquete Node en javascript al estilo del de Java

Estas 3 implementaciones (y a lo mejor alguna más que no conozca) son fáciles de instalar y están destinadas a ser ejecutadas por línea de comando o integradas en un proceso de construcción de software.

Instalación

Si usas Ruby, Asciidoctor se puede instalar como una gema:

gem install asciidoctor

O bien puedes instalarlo como paquete del sistema operativo:

sudo apt-get install asciidoctor

Si no quieres instalar dependencias de Ruby y prefieres utilizar la implementación en Java puedes descargar el _jar_de su web o si tienes SdkMan como gestor de aplicaciones, puedes instalarlo fácilmente:

sdk install asciidoctorj

Ejemplo básico

Abre un editor de texto plano (recuerda ni Word ni LibreOffice son editores de texto plano) como notepad, gedit, vi o nano y escribe:

ejemplo.adoc

= El titulo : el subtitulojorge.aguilera@puravida-software.com(debes dejar un espacio en blanco entre el email y esta linea)== Una sección*Todo* lo que ven tus ojos algún día _sera_ tuyo

Guarda el documento comoejemplo.adoc y desde una línea de comando nos situamos donde esté el documento y ejecutamos:

asciidoctor ejemplo.adoc ( oasciidoctorj ejemplo.doc si usamos la versión java)

Si todo ha ido bien debería haberse generado un documentoejemplo.html que puedes abrir con un navegador y comprobar que es un documento html5 completo y que se ha generado sin necesidad de tener conocimientos de maquetar html

Editores

La sintáxis de asciidoc es muy completa y extensa pero a la vez muy sencilla por lo que una vez practicado con ella serás capaz de memorizar gran parte de ella por lo que no deberías necesitar más que un editor plano.

Sin embargo hay editores y/o plugins para diferentes IDEs que nos pueden ayudar a escribir en asciidoc. A modo de ejemplo dispones:

• AsciidocFX (requiere Java)

• IntelliJ (requiere instalar un plugin)

• VSCode (requiere instalar un plugin)

De forma general, y aunque estos editores tengan la opción de generar el html (o el pdf, etc) es importante entender que estos editores trabajan sobre eladoc y que nosotros podremos ejecutar la generación del documento utilizando todas las opciones que ofrecen.

1. https://asciidoctor.org/docs/asciidoc-vs-markdown/