Una nueva web

Ya iba siendo hora de repasar la web. Y qué mejor que usar Antora y Asciidoc.

jBake

En septiembre de 2016, el proyecto NetBeans fue donado por Oracle a la Apache Software Foundation.

En octubre de 2016 el proyecto entró en fase de incubación, hasta el 17 de abril de 2019, en el que se graduó como uno más de los proyectos de Apache.

Una de las tareas durante esta fase de incubación consistió en migrar la gran cantidad de sitios web de NetBeans (plugins.netbeans.org, platform.netbeans.org, wiki.netbeans.org, netbeans.org y otros muchos) a la única web del proyecto Apache.

Para ello utilizamos un proyecto Gradle que usaba el generador de sitios estáticos (SSG - Static Site Generator) jBake. El proyecto nos sirvió bastante bien durante muchos años.

Hace un mes o así se decidió cambiar jBake por Antora, un generador de sitios estáticos mucho más potente, diseñado específicamente para construir documentación técnica, aunque puede adaptarse para generar sitios web más normalitos. Como éste.

Antora

Qué mejor momento que éste para actualizar mi sitio web, construido con un SSG "a medida" por Antora, ¿no? La oportunidad es ideal para aprender algo de Antora y actualizar mi web con un nuevo SSG más estándar.

Y dicho y hecho. He actualizado mi web. Eliminando mucho contenido anticuado y empezando también a escribir este blog.

Resumo aquí algunas curiosidades de Antora, por si son de utilidad a otros.

Forma y fondo

Las webs construidas con Antora separan claramente la forma (el aspecto visual) del fondo (el contenido). Esto es siempre una buena práctica. Aunque, como suele pasar, siempre hay algunos puntos de contacto que no son del todo ideales, pero la separación es bastante buena.

La forma

Antora proporciona un Antora Default UI, un interfaz por defecto que está bastante bien. Uno puede seguir la excelente documentación y clonarse el repositorio antora-ui-default para personalizarlo.

Antora UI Default usa una colección de hojas de estilo CSS. A pelo, es decir, sin usar Sass. Las hojas de estilo están bastante bien clasificadas en ficheros, y un linter asegura que se siguen las guías de estilo.

Además de las hojas de estilo el interfaz por defecto proporciona:

  • Una serie de extensiones JavaScript, que permiten crear funciones para acceder y manipular el contenido.

  • Un conjunto de plantillas HandleBars. Obviamente cada cual puede añadir las que considere convenientes. Estas plantillas se complementan con una colección de partials, o bloques, que renderizan diferentes partes de las páginas web (la cabecera, el pie de página, etc.).

  • Varios scripts JavaScript que se incluyen automáticamente en las páginas, y que se responsabilizan de diferentes cosas, como generar la tabla de contenidos, por ejemplo.

El fondo

El contenido del sitio web se basa únicamente en Asciidoctor, una variación de AsciiDoc.

Este contenido se estructura en diferentes repositorios, según la documentación oficial de Antora. Esto está bien si, por ejemplo, diferentes partes de la web tienen diferentes versiones, por ejemplo, para diferentes componentes de una librería de software que tengan diferentes ciclos de vida y vayan versionados independientemente.

Usar repositorios adicionales está bien para sitios grandes, para sitios pequeños como éste es suficiente crear uno o más directorios, sin complicarse la vida, y leer el contenido de ahí. Esto no está muy bien documentado en la documentación oficial de Antora, el truco consiste en modificar el fichero principal antora-playbook.yml y añadir el directorio donde tengamos el contenido. En mi caso:

site:
  title: vieiro.net
  url: https://vieiro.net
  start_page: web::index.adoc
content:
  edit_url: ~
  sources:
  - url: .
    start_path: web
    branches: HEAD

Esto es, ponemos como url el directorio actual (.) en vez de un repositorio git, e indicamos un start_path donde vayamos a poner el contenido.

Extensiones

Antora es bastante "extensible", uno puede hacer archivos JavaScript que modifiquen el contenido, por ejemplo. La documentación es algo confusa, pero hay ejemplos en internet que pueden ayudar. Uno de estos scripts puede servir para hacer un fichero atom.xml con las entradas del blog. Como, por ejemplo, éste de Eric Barboni para NetBeans.

Búsqueda

Antora se integra bien con motores de búsqueda en el cliente (como lunr) pero también con otros más potentes, en el servidor, como Algolia.

MathJAX

También puede incluirse una extensión de MathJAX (esto es un poquillo más complicado) para renderizar contenido mátemático con facilidad.

Por ejemplo, este código en Asciidoctor:

stem:[[[a,b\],[c,d\]\]((n),(k))].

Se renderizaría luego como esto:

.

Conclusiones

Antora parece ser bastante potente para publicar sitios webs con carácter técnico, y parece que puede servir también para publicar sitios web personales como éste. Durante los próximos meses iré comentando diferentes trucos para sacarle el mayor partido.