pandoc y sus capacidades

Posted on by

Resulta que acostumbro a crear páginas web de aterrizaje en servidores que llamo administrativos porque no tienen en su página principal un propósito concreto como un blog o un wiki, pero si disponen de aplicaciones web en URL internos como estadísticas web y herramientas administrativas para gestionar bases de datos o directorios LDAP o, incluso, un monitorizador de recursos.

Todos ellos son accesibles directamente desde fuera pero a mí me gusta saber qué tengo instalado y mantenido en una única página.

De esta forma puedo proteger todos los acceso en un único punto con el servidor web empleando el módulo de autorizaciones normalizado y si a eso le añado una conexión segura forzada más o menos queda listo para enfrentarse al mundo. Hay otras medidas, pero ya no tienen que ver con lo que quiero contar aquí. 

<VirtualHost *:443>
        ServerName  tlp.zeine.es
        ServerAlias tlp
        ServerAdmin admin@eine.es

        DocumentRoot /var/www/html/tlp.zeine.es
        <Directory /var/www/html/tlp.zeine.es>
                Options FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>

        LogLevel warn
        ErrorLog /var/log/apache2/tlp.zeine.es/error.log 
        CustomLog /var/log/apache2/tlp.zeine.es/access.log combined

        Include /etc/apache2/ssl.conf

        <Location />
                AuthType Basic
                AuthBasicProvider ldap
                AuthName "Herramientas administrativas"
                AuthLDAPURL "ldap://localhost/ou=users,dc=zeine,dc=es?uid?sub?(objectClass=*)"
                Require valid-user
        </Location>

        Include /etc/apache2/sites-conf/tlp.zeine.es/*.conf
</VirtualHost>

Indicarle a Apache que el URL raíz está bajo control de acceso permite quedarse tranquilo en este aspecto porque abrir un nuevo navegador e ir a una URL interior nos enseña lo mismo que comenzar por el índice:

Para realizar todos estos ajustes en el servidor las empaquetado en formato deb, un paquete por cada servidor empleando herramientas como equivs, por lo que es sencillo que sean fáciles de integrar y respetuosas con las reglas.

Sí, es verdad que podría utilizar sistemas como puppet o Ansible pero de momento estoy muy perezoso con el asunto. ¿ Por qué ? Porque cualquier de los dos requiere una curva de aprendizaje para la que no tengo tiempo ahora mismo. También que hay ciertos vaivenes de cuando en cuando con su popularidad y no termino de decidirme por uno u otro. Si no trabajase solo algo de ésto habría adoptado ya, siempre quiero aprender cosas útiles o con posibilidades, pero así no encuentro el impulso para ello.

Cuando llega el momento de crear la página índice del servidor no quiero escribir a mano el código HTML así que empleo el lenguaje markdown y un programa externo llamado pandoc que realiza toda la magia.

![](/images/zeine-logo.png)

### Aplicaciones administrativas

* [Administración de MySQL (phpmyadmin)](https://tlp.zeine.es/mysql){target="\_blank"}
* [Monitorización del sistema (munin)](https://tlp.zeine.es/munin){target="\_blank"}

### Estadísticas web 

* Servidores:
  * [Página principal](https://tlp.zeine.es/awstats/awstats.pl?config=zeine.es){target="\_blank"}
  * [Versión
  antigua](https://tlp.zeine.es/awstats/awstats.pl?config=antigua.zeine.es){target="\_blank"}
  * [Zona
administrativa](https://tlp.zeine.es/awstats/awstats.pl?config=tlp.zeine.es){target="\_blank"}
* Aplicaciones web:
  * [Nube bajo
Nextcloud](https://tlp.zeine.es/awstats/awstats.pl?config=nube.zeine.es){target="\_blank"}
  * [Correo vía
web](https://tlp.zeine.es/awstats/awstats.pl?config=correo.zeine.es){target="\_blank"}
  * [Listas de
correo](https://tlp.zeine.es/awstats/awstats.pl?config=listas.zeine.es){target="\_blank"}

Es tan sencillo como indicarle lo siguiente:

$ pandoc -f markdown -t html -o index.html index.md

Y el resultado es de lo más apañado como se ve en la imagen superior. Le faltan detalles, claro, porque la conversión se realiza a través de complementos (integrados en el propio programa) y estos necesitan más información.

La lista de parámetros esenciales para tener un documento HTML correcto es:

  • standalone: para añadir el encabezado y el pié HTML con las directivas correctas.
  • metadata KEY=[VAL] que define aquellos valores que queremos incluir como el título (title) o el lenguaje (lang). Sirven también para emplearlos en las plantillas de conversión, que son otro mecanismo fantástico pero que aún no he necesitado.

Enlaces abriendo en otra ventana o pestaña

Uno de los problemas tontos que me he encontrado con el archivo index.html resultante es que los enlaces HTML son muy básicos. Teniendo en cuenta que las aplicaciones que suelen abrir no tienen una forma sencilla de volver atrás, a esta página principal, y que es posible que quiera abrir varias de ellas al mismo tiempo, he pensado que si los enlaces HTML ya lo hiciesen por mí estaría genial.

Así es como he descubierto que el enlace markdown en versión simple (entendido desde el punto de vista de pandoc) sería:

[Texto del enlace](https://example.com)

se me queda corto para lo que quiero. Tengo la opción de escribir directamente el código HTML pero entonces pierde la gracia.

El componente que crea el código admite la siguiente construcción: 

[Texto del enlace](https://example.com){target="\_blank"}

para definir los atributos de la etiqueta a de html y aunque tengo que añadírselos a todos porque aún no sé cómo declararlos como predeterminados sigue siendo cómodo y rápido. A propósito, el carácter subrayado está escapado porque markdown lo reconoce como directiva de síntaxis.

Metadatos

Cuando tienes que pasarle un par de valores como metadatos hacerlo en la línea de órdenes es sencillo a pesar de que algunos como el título pueden ser largos. Pero si empiezan a crecer es mejor utilizar el mecanismo de reconocimientos de bloques de metadatos.

Empleando el formato YAML es posible añadir esos metadatos en el propio código fuente markdown de esta manera:

---
title: TITULO
lang: es
---
![](/images/zeine-logo.png)

### Aplicaciones administrativas

* [Administración de MySQL (phpmyadmin)](https://tlp.zeine.es/mysql){target="\_blank"}
* [Monitorización del sistema (munin)](https://tlp.zeine.es/munin){target="\_blank"}

Por lo que el resultado empleando el parámetro –standalone está correctamente completo:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="es" xml:lang="es">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>TITULO</title>
  <style type="text/css">
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}

Y hasta aquí lo que he descubierto esta mañana de sábado y que me va a facilitar mucho la vida ampliando esta técnica de un paquete por cada servidor.

Referencias