Crea tu portal con Antora

Submitted by elmanytas on

A la hora de crear un portal siempre nos encontramos con los mismos problemas: la gestión de permisos, la "caducidad" de la plataforma, el formato de la documentación, la gestión manual de la documentación, uniformidad de los estilos en todos los portales, transformación entre diferentes formatos, ...

Antora es un generador de portales a partir de AsciiDoc, lo cual se suma a la facilidad que tiene para transformarse en varios formatos como epub, pdf o html.

Tendencias

Desde hace unos años podemos ver como diferentes empresas desarrollan su documentación usando un lenguaje de marcado organizado en repositorios:

Soporte

Existen plugins de AsciiDoc para los CMS más populares como pueden ser Wordpress o Drupal. Y lo mismo con Markdown.

También tenemos plugins para los principales IDEs que permiten ver en tiempo real el resultado de tu trabajo:

Github Atom Microsoft Visual Studio Code
Atom Code

Y por supuesto, tal como has podido ver pinchando en los enlaces de tendencias, están soportados de caja en cualquier servicio de git que ofrezca una mínima funcionalidad como Github o Gitlab.

Sintaxis de lenguajes de marcado

Hay unos que se caracterizan por ser más fáciles y otros más difíciles pero con más funcionalidad.

Por ejemplo, para poner énfasis en algo tenemos lo siguiente:

Markdown AsciiDoc DocBook
texto en **negrita** texto en *negrita*

texto en <emphasis>negrita</emphasis>

Resumir toda una sintaxis en tres líneas es muy difícil pero esto nos da una idea de que Markdown y AsciiDoc pueden llegar a parecerse en cuanto a simplicidad mientras DocBook, al usar xml, puede ser más tedioso.

La tendencia ha sido simplificar todo lo posible la edición manteniendo toda la funcionalidad necesaria y por eso lo más usado suele ser Markdown o AsciiDoc. Por supuesto que existen otros formatos como Doxygen, que son perfectamente válidos, pero parece que el mercado tiende a Markdown o AsciiDoc dependiendo del uso.

¿Markdown o AsciiDoc?

Si queremos un documento que al mostrarse por la web tenga enlaces a otros documentos pero al generarse el PDF se incrusten, deberemos poner en AsciiDoc:

ifdef::env-gitlab,env-github,env-browser[]
Secciones:

* link:./arquitectura/arquitectura.adoc[Arquitectura]
* link:./infraestructura/infraestructura.adoc[Infraestructura]

endif::[]

ifdef::ebook-format-kf8,backend-pdf[]

include::./arquitectura/arquitectura.adoc[]
include::./infraestructura/infraestructura.adoc[]

endif::[]

Si quieres hacerlo en Markdown, no podrás.

AsciiDoc tiene bastantes funcionalidades que Markdown no tiene y su uso es casi igual de fácil.

En Markdown ha habido intentos de incluir funcionalidad que en AsciiDoc viene de caja pero han desembocado en distintas implementaciones que pueden funcionar o no dependiendo del servicio que utilices.
Por ejemplo, la implementación de Gitlab es distinta a la de Github, lo que supone un problema en cuanto a portabilidad.

Renderizando, ando

Vamos a renderizar este documento a diferentes formatos a partir de este archivo, como son:

  • html: docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor antora.adoc
  • pdf: docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf antora.adoc

Para renderizar un documento hemos usamos la imagen docker-asciidoctor que la organización mantiene en dockerhub.

Creando un portal

Podría subir los html estáticos a un servidor y ya tendría mi portal, pero existen frameworks que permiten generar portales fácilmente tomando como fuentes uno o varios repositorios.

En la wikipedia nos encontramos con tres frameworks cuyas pruebas me han hecho llegar a las siguientes conclusiones:

Antora

Antora permite la creación de un portal a partir de un playbook en formato yaml donde se definen todos los repositorios que lo forman.

De esta forma podemos tener diferentes repositorios para sistemas, seguridad, desarrollo, …​ y Antora se encargará de juntarlos todos en un solo portal al que aplicará los mismos estilos. Cada uno de esos repositorios es un "componente" del portal para Antora.

En cada repositorio (componente) necesitamos crear un archivo llamado antora.yml donde definiremos las secciones que formarán este componente. Cada una de esas secciones es un "módulo" para Antora.

Si el repositorio tiene varias ramas nos puede crear una versión del componente por cada una de ellas.

Un ejemplo de Antora

Por suerte la documentación oficial es realmente clara en este aspecto pero voy a intentar simplificarla más.

Clona el siguiente repositorio:

git clone https://gitlab.com/antora/demo/demo-site

Dentro del repositorio verás el playbook site.yml con este contenido:

site:
  title: Antora Demo Site
  # the 404 page and sitemap files only get generated when the url property is set
  url: https://example.org/docs
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: master
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Este archivo indica a antora que la raíz del portal (site.start_page) será el archivo index.adoc del componente b.

Además irá a los dos content.sources y generará sus html con la versión master para el primero mientras para el segundo generará las versiones v2.0 y v1.0 partiendo del directorio docs.

Ejecuta esto para generar los estáticos:

docker run -u $UID --privileged -v `pwd`:/antora --rm -t antora/antora site.yml

Tu portal ahora se encuentran en build/site/index.html

Cambios para construir un portal

Imagina que tienes un archivo en AsciiDoc llamado antora.adoc en un repositorio y quieres cambiar su estructura para tener un portal. Todo el contenido está en la rama master de un único repositorio ubicado en https://github.com/elmanytas/antora-examples:

  • mueve antora.adoc a modules/ROOT/pages/antora.adoc.
  • mueve las imágenes a modules/ROOT/assets/images/.
  • crea modules/ROOT/pages/_attributes.adoc con este contenido:
    :moduledir: ..
include::{moduledir}/_attributes.adoc[]
  • crea modules/ROOT/_attributes.adoc con este contenido:
    :attachmentsdir: {moduledir}/assets/attachments
:examplesdir: {moduledir}/examples
:imagesdir: {moduledir}/assets/images
:partialsdir: {moduledir}/pages/_partials
  • crea un modules/ROOT/nav.adoc con el contenido de la barra de navegación:
    xref:antora.adoc[Antora]
  • crea un antora.yml con este contenido en la raíz del repositorio:
    name: antora
title: antora
version: antora
nav:
- modules/ROOT/nav.adoc

  • crea un site.yml con el siguiente contenido en la raíz del repositorio:

    site:
  title: Post de Antora
  # the 404 page and sitemap files only get generated when the url property is set
  url: http://antora.example.com
  start_page: antora::antora.adoc
content:
  sources:
  - url: https://github.com/elmanytas/antora-examples.git
    branches: antora
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

A partir de este momento puedes trabajar tal como lo hacías antes escribiendo en modules/ROOT/pages/ y dejando las imágenes en modules/ROOT/assets/images/. Todo lo que escribas aparecerá en tu portal ejecutando:

docker run -u $UID --privileged -v `pwd`:/antora --rm -t antora/antora site.yml