¿Cómo he llegado aquí?

-> Alert text <-

El presente es el enésimo intento de tener mi propio blog, esta vez usando Zola que es un generador de páginas web estáticas como cualquier otro pero con una pésima documentación.

Zola es un programa monobloque escrito en Rust cuyas opciones pueden ser consultadas en Zola CLI Usage. No obstante lo esencial para usar Zola es conocer su estructura de directorios.

Zola espera del usuario que estructure sus archivos de una forma determinada y distingue básicamente entre Secciones, Páginas, Plantillas y estilos para lo que usa SASS que es un preprocesador de CSS.

Lo que hace Zola es, en resumidas cuentas, renderizar como html las distintas páginas que conforma el sitio, que se escriben en formato Markdown (.md) y que son "mezcladas" con las plantillas utilizando el motor Tera cuya síntaxis es muy similar a la de Jinja2 u otros motores de plantillas como las de Django.

Lo más importante que hay que saber es que gracias a la comunidad existen mutitud de temas que nos permitirán empezar con Zola directamente editando los archivos .md, eso sí realizando previamente algunos cambios a la configuración. De los distintos temas disponibles elegí Duckquill para empezar, si bien puede ser que en el momento de que leas esto esté utilizando uno distinto.

De los pocos temas que probé cuando empecé en Zola ninguno estuvo libre de incidentes y ninguno funcionó bien desde el principio, y aunque la verdad es que los foros correspondientes tienen bastante actividad al ser software muy específico es fácil que te encuentres con algún problema sin resolver con el que te tocará hacer algo de ingeniería inversa y unos buenos golpes de ensayo-error.

Pero bueno para empezar como he llegado aquí debo decir que el sitio web se ha montado sobre un VPS Debian Trixie. Zola no se encuentra en los repositorios de Debian, y aunque compilarlo es una opción, teniendo en cuenta el espacio de VPS no quise instalar todas las herramientas de desarrollo necesarias por lo que opté por el paquete precompilado para mi SO en zola-debian. He aquí los pasos:

$ wget https://github.com/barnumbirr/zola-debian/releases/download/v0.22.1-1/zola_0.22.1-1_amd64_trixie.deb
$ sudo dpkg -i zola_0.22.1-1_amd64_trixie.deb
$ zola --version

Lo siguiente era buscar un buen lugar donde alojar el sitio dentro de mi sistema de archivos, /srv/blog fue el directorio elegido. Una vez en el directorio se puede inicilizar todo el sistema de directorios con la opción init del ejecutable.

$ mkdir /srv/blog && cd /srv/blog
$ zola init

Inicialmente dejé las opciones por defecto, con excepción del sitio donde puse el de la dirección que te ha llevado aquí. Hecho esto, aunque en su momento seguí el tutorial para dar forma a tu primer sitio debo decir que no se aprende gran cosa con ello. Si estás pensando en usar Zola para tu sitio te recomiendo que directamente vayas a por alguno de los temas. Te indico lo que hice yo desde ese momento:

$ git clone https://codeberg.org/daudix/duckquill.git themes/duckquill

En este momento puedes hacer una prueba de que todo va como debe de ir ejecutando lo que sigue y accediendo desde cualquier navegador a la dirección http://127.0.0.1:1111 (consultar las opciones de línea de comandos para servir en otras direcciones y/o puertos).

$ zola serve

Si has seguido los pasos verás que únicamente se muestra la pantalla de bienvenida que es lo que se muestra cuando ninguna página ha sido escrita. Zola buscará como página inicial _index.md dentre del directorio content.

+++
+++
# Esto es una prueba

Esta sería mi página de entrada

Los tres signos de sumar tienen un sentido, lo que hay entre ambas líneas es lo que se llama el front-matter y es absolutamente necesario, aunque esté vacío. En ese lugar se añaden opciones de configuración que amplían o sobreescriben las establecidas en el archivo config.toml, que aún no he nombrado pero que es necesario tocar para que la nueva página sea renderizada. Yo añadí las siguientes dos líneas al inicio de tal archivo config.toml:

title="Arrecio's blog"
theme="duckquill"

Y con esto ya se renderiza la página con los estilos del tema elegido siendo cierto que la web de Duckquill resulta mucho más ágil y llamativa.

Dicha web es suministrada como ejemplo dentro de la carpeta themes/duckquill/content pero si la copiamos directamente a la raiz de nuestro blog encontraremos bastantes problemas empezando por las referencias a que los archivos de localización para distintos idiomas no contienen el front-matter y además no se suministra un config.toml operativo ya que al copiarlo directamente los problemas se acrecentan. Para aprender como Zola termina publicando el sitio lo mejor es ir poco a poco.

$ cp themes/duckquill/content/_index.md content/

Realizado esto nuestro Zola ya está sirviendo la página de entrada de la web de Duckquill, en mi caso el color del fondo es un azulado a diferencia del marrón claro de la web original. Además el pie de página no aparece en mi caso y el menú flotante para navegar tampoco. Esto no es por que nos falten otros archivos sino porque nuestro config.toml no contiene los valores adecuados.

Aunque como he dicho copiar el config.toml de themes/duckquill/ lo único que nos aporta es más errores, sí que es cierto que parte de su contenido nos va a ser útil en el futuro, pero no estamos en ese momento.

Ahora es un buen momento para comentar que cualquier fichero que penda de themes/duckquill/templates/ o themes/duckquill/static/ será ignorado si a su vez existe un fichero con el mismo nombre en templates/ y static/ respectivamente. A partir de ahora me referiré únicamente como directorio templates o directorio static pudiendo el documento estar alojado en uno u otro sitio siguiendo la regla anterior.

El renderizado de la página de entrada se hace expandiendo el archivo index.html del directorio de templates. El contenido de ese _index.md es expandido en section.content esto es porque nuestra página de entrada es tratada como una sección. Lo que hace que cierto contenido de una carpeta se trate como sección es precisamente el carácter _ antes de index.md. El directorio raíz de contentsiempre se entiende como sección por lo que debe contener al menos el documento _index.mdpara dotarla de contenido.

Zola renderiza el sitio a partir de la raíz del directorio content por lo que si creamos más directorios podremos navegarlos ampliando la dirección de nuestro sitio en el navegador. Si en el directorio existe un _index.mdentonces se trata como sección, sino se tratan sus archivos .md como páginas individuales. Como nota a añadir, pueden establecerse nombres distintos entre los caminos establecidos en disco y los de la url mediante alguna modificación del front-matter del index pero no me voy a detener en algo que hasta el momento ni tan siquiera he probado.

Cuando una carpeta es tratada como sección entonces también se tratan el resto de documentos que no tienen formato Markdown, los cuales son tratados como documentos auxiliares accesibles para las páginas como assets.

He hablado del archivo templates/index.html que como he dicho es usado para la página de entrada pero existe dos ficheros básicos más: template/secontion.html y template/page.html. Estos son las plantillas de Tera a partir de las cuales se expandirán los documentos _index.htmlde otras secciones y cualquier documento .md respectivamente. Respecto a las páginas, el contenido de los archivos ´.md´ (más allá del front-matter) se expande con page.content, en analogía al section.content que se utiliza para los documentos _index.md.

Pero los anteriores son las plantillas por defecto. A través del front-matter de cualquier página o sección podemos cambiar el nombre del documento html con la plantilla a expandir para ese particular claso. Por ejemplo este sería un front-matter para una página que se expande con otra plantilla llamada about.html:

+++
title = "About Us"
template = "about.html"
+++

Llegados hasta aquí faltaría un único punto importante a introducir, la Paginación. Páginar en un entorno Zola significa básicamente dividir el contenido en distintos elementos y proveer un sistema de ordenación y/o de navegación entre los mismos.

Si viajamos a la página principal de Duckquill veremos que la primera página no parece contener ningún tipo de paginación, y así es. En el navegador flotante que encontramos en la parte superior de la página podemos dirigirnos al Blog el cual si está paginado conteniendo dos elementos por página. A su vez cada elemento se muestra como una especie de tarjeta.

Para comprender el sistema de paginación de Duckquill veamos el archivo content/blog/_index.md:

+++
title = "Writings of Duck's Feet"
sort_by = "date"
template = "article_list.html"
page_template = "article.html"
paginate_by = 2
+++

Welcome to my quack'in blog, I quack about various stuff, but mostly I'm a demo.

En el mismo vemos que dentro del front-matter establecemos dos plantillas personalizadas, para cada página usamos article.html que es la plantilla de las tarjetitas. Para el archivo _index.md en si utilizamos como plantilla article_list.html.

Examinando la estructura que pende de content/blog vemos que existen varios directorios, todos ellos son referentes a distintas páginas, esto es porque no contienen un archivo _index.md sino uno index.md. Zola escanea el directorio de la sección blog para detectar todas las páginas definidas en el mismo y para ordenar las mismas se utiliza el campo date.