Introducción a Asciidoc y Asciidoctor (1)
Tags: asciidoc, documentation, write
Published: 2020-01-08 14:20:31

---
title: Introducción a Asciidoc y Asciidoctor (1)
published: true
date: 2020-01-08 00:00:00 UTC
tags: asciidoc,documentation,write
canonical_url: https://jorge.aguilera.soy/blog/2020/intro-asciidoctor-1.html
---

| | 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](http://asciidoc.org) )

Con esta definición lo primero que pensarás es que es otro **Markdown** 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 las **diferencias son enormes**.<sup>[<a id="_footnoteref_1" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>

Se podría decir que **Asciidoc** 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 usado **reStructuredText** entonces puedes ver a **asciidoc** como otra alternativa a este. |

**Asciidoctor** ([https://asciidoctor.org](https://asciidoctor.org)) es una **implementación** , un programa, un ejecutable, que es capaz de leer documentos _asciidoc_ 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 llamada **asciidoc** , igual que las especificaciones, pero que su última actualización es del 2013. Así, cuando en este documento hable de **asciidoc** estaré hablando de las especificaciones y no de esta implementación. |

La implementación **asciidoctor** 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 subtitulo
jorge.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 como `ejemplo.adoc` y desde una línea de comando nos situamos donde esté el documento y ejecutamos:

`asciidoctor ejemplo.adoc` ( o `asciidoctorj ejemplo.doc` si usamos la versión java)

Si todo ha ido bien debería haberse generado un documento `ejemplo.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 el `adoc` y que nosotros podremos ejecutar la generación del documento utilizando todas las opciones que ofrecen.

* * *

1. [https://asciidoctor.org/docs/asciidoc-vs-markdown/](https://asciidoctor.org/docs/asciidoc-vs-markdown/)