En una publicación pasada traté de dar un panorama bastante informal de los sitios web estáticos, la problemática que pueden resolver y algunas de las herramientas para armarlos.

En esta ocasión les mostraré, espero paso por paso, como hacer un sitio estático con pelican y en la siguiente publicación subirla a codeberg. Mucho de esto puede extrapolarse a otras herramientas, quizá sólo hay detalles relevantes que cambian si el sitio será alojado en gitlab pages. Para ese caso me parece una mejor metodología partir de forkear (meterle mano) a los ejemplos que se listan en la página, pero quizá en una futura publicación podamos ver un poco al respecto.

Voy aprendiendo a la par que escribo, así que veamos esta publicación como un aprendizaje colectivo, para nada soy un experto, pero quizá de mi experiencia y de mis muchos errores algo bueno pueden sacar.

Antes de poner manos a la obra les platico de Pelican.

Pelican

Pelican es un generador de sitios estáticos escrito en python, desarrollado y actualizado por Justin Meyer junto con más miembros del equipo de desarrollo de Pelican. Es software libre con una licencia GNU Affero General Public License, el código fuente pude consultarse y descargarse desde https://github.com/getpelican/pelican, pero puede instalarse desde repositorios o desde el mismo pip de python.

Como les mencioné en la pasada publicación la ventaja de estar en python es la popularidad del lenguaje, las librerías quizá ya las tienen los usuarios de python y no ocupan tanto espacio. Para los que no sean experimentados programadores¹ no se preocupen, no requieren saber mucho de la sintaxis de python, básicamente su uso se limita a unos pocos comandos en terminal, muy sencillos y directos, no hay que temerle a usar texto (recuerden es el leitmotiv de esta bitácora).

El nombre hace referencia al pelicano, pero se debe a que pelican es un anagrama de calepin, "libreta de notas" en francés. Las entradas puede ser escritas en formatos markdown o reStructuredText, dos opciones sencillas que tienen como base la idea de "lo que ves es lo que obtienes", es decir, nada de código que dificulta la lectura, texto plano y solo unas pequeños atajos para dar formato.

Para editar las entradas pueden usar el editor de texto de su preferencia, en mi caso uso emacs por tradición heredada, pero pueden hacer uso de vim, geany, el bloc de notas, cualquier herramienta para editar texto plano (sin enriquecimiento). Esto puede ser útil incluso si desean posteriormente convertir sus entradas a otro formato, que puede hacerse con ayuda de pandoc (pero ese es tema de otra publicación muy próxima).

Instalando Pelican

Partiré de que todos usamos gnu/linux, en caso de estar desde windows o macOS entiendo no cambia mucho el método, mientras puedan abrir una línea de comando y ya cuenten con python va a ser bastante directo.

Para las distribuciones derivadas de debian pelican se encuentra en los repositorios, pueden descargarlo directo de ahí, aunque quizá no es la versión más actualizada. Pero para no dejar a nadie fuera partamos de que se tiene python3 junto con pip. En la línea de comandos escribimos:

 python -m pip install "pelican[markdown]"

En mi caso sin el [markdown] funcionó, y puede que deban cambiar python por python3, dependerá de su sistema, pero dejo la versión del sitio. Instalará unas cuantas librerías, en algunos casos pedirá que el comando lo corramos como súper usuarios. Si todo sale bien pelican está instalado.

Armando un sitio

Para hacer nuestro sitio web estático debemos crear un directorio donde se guardarán los archivos, los que usemos para crearlo y los que subiremos al servidor. Creamos el directorio con el nombre que nos guste, en mi caso lo llamaré pelicano, ustedes decidan el mejor lugar para ponerlo (puede ser en Documentos, su directorio home/, o incuso hacer un directorio especial para sus varias páginas que harán)

 mkdir /path-to/pelicano
 cd /path-to/pelicano

Recuerden cambiar /path-to/ por la ruta que corresponda a su caso, si ya están en el directorio pueden ahorrarse toda la ruta, pero lo dejaré de la manera más general. Ya nos encontramos en el directorio creado, está vacío como una casa a la que nos acabamos de mudar, vamos a ponerle los muebles.

Para inicializar el sitio lo más fácil es escribir el siguiente comando en terminal:

pelican-quikstart

Esto producirá los archivos y directorios necesarios para empezar a armar nuestro sitio. Pero nos pedirá darle alguna información para hacerlo un poco más veloz.

1. Debemos decirle donde deseamos crear el sitio, como ya estamos en el directorio pelicano basta con darle enter, elegirá la opción por omisión que es el directorio en el que estamos.
2. A continuación preguntará el nombre del sitio, podemos escribir mayúsculas, espacios, acentos.
3. Pedirá el nombre del autor del sitio, escribimos nuestro nombre o alias.
4. ¿El lenguaje del sitio? Nos dará por omisión el lenguaje definido de su sistema, pero podemos elegir en, es, el que decidamos.
5. Pedirá un prefijo para la URL del sitio. Esto es útil si lo hacemos desde un servidor y hay un dominio del cual será subdirectorio, ya desde su creación quedará la ruta correcta, pero en este momento está bien si le decimos que no.
6. Nos preguntará si deseamos activar la paginación de los artículos. Esto activa las opciones para la cantidad de artículos que se muestran en la primer página. El comportamiento normal de pelican es mostrar el título y las primeras líneas del mismo, esto se puede manipular con algunas variables. Si el sitio tendrá muchas publicaciones conviene habilitar la paginación, pongamos que sí.
7. ¿Cuántos artículos deseamos ver por página? El valor por omisión son 10, pero podemos ajustar al gusto. Estos valores pueden cambiarse después manipulando un poco los archivos.
8. ¿Cuál es nuestra zona temporal/huso horario? Para saber qué valores son válidos revisen la tabla que se da en wikipedia. Mi caso es America/Mexico_City.
9. ¿Deseamos generar un Makefile y el programa task.py para automatizar el proceso? Esto es opcional y en nuestro caso no lo usaremos. Estas opciones permiten hacer cambios de manera automática sólo llamando los archivos, ya contienen algunas de las características dadas durante este cuestionario, pero se pueden personalizar un poco más. Sí decimos que sí se generarán los archivos, pero si no los necesitamos podemos borrarlos en cualquier momento y no alteran en nada el armado del sitio.

Una vez respondidas todas las preguntas el sitio ya estará listo en el directorio que decidimos, pelicano/. Desde ese directorio podemos listar los archivos contenidos, hallaremos lo siguiente

• Los directorios:
  • content/
  • output/
• Los archivos:
  • pelicanconf.py
  • publishconf.py
• Y en caso hayamos dado que sí a la última pregunta:
  • Makefile
  • task.py

Esto es todo lo que necesitamos para amar nuestro sitio, no tenemos que correr en python los archivos, los comandos de pelican se encargarán de eso. Si acaso hay algunas cosas que podemos manipular en estos archivos para tener el sitio tuneado a nuestro gusto, pero con eso ya podremos ir jugando al paso del tiempo.

Ambos directorios están vacíos, digamos que hemos puesto las cortinas pero falta ir llenando de tiliches la bitácora. El directorio content será donde se encuentren los archivos de texto de nuestros artículos. El directorio output tendrá los archivos html de nuestro sitio, a subir al servidor. Por el momento no cambiemos de nombre los directorios, el programa buscará ahí sus archivos y de cambiar de nombre la carpeta puede que no los encuentre. Podemos cambiar nombres una vez nos familiaricemos con el uso de pelican.

Procedemos a escribir una primera publicación en formato markdown. Podemos crearlo desde terminal:

  cd /path-to/pelicano/content/
  touch primera-publicacion.md

O abrir desde nuestro editor de texto y ahí darle guardar. Si ya creamos el archivo, pasamos a abrirlo con el editor de texto y escribimos dentro:

Title: ¿Qué pasión?
Date: 2022-01-11
Category: saludos

Esta es la **primera** publicación de mi *bitácora*. Bienvenidxs.

Guardan el archivo (recuerden que debe terminar en .md para ser identificado en ese formato) y ya tienen el primer contenido para su sitio, lo que sigue es convertirlo en html.

Para ir armando el sitio escriban el siguiente comando en terminal

 pelican /path-to/pelican/content

al comando pelican debe darse como argumento el directorio donde están los archivos de los artículos. Este directorio puede contener los subdirectorios pages/ para las páginas permanentes (sobre el sitio, contacto, etc.) e images/ para las imágenes que vayamos a publicar (recordemos dar la ruta correcta al agregar imágenes con markdown).

Esto puede producir algunos warnings que no afectarán el armado del sitio, en caso de errores al dar la información inicial nos lo dirá. Al final de esos avisos nos informará qué procesó, en nuestro caso aparecerá

 Procesed 1 article, 0 drafts, 0 hidden articles, 0 pages, 0 hidden pages and 0 draft pages in <time> seconds

Como podemos ver es bastante rápido, pero tampoco tenemos tanto contenido.

En este punto seguro nos comen las ansias de ver el resultado, antes de verlo revisaremos que la carpeta output/ tiene bastantes archivos y carpetas, la mayoría en html. No es necesario abrir archivo por archivo para verlo, si queremos ver el sitio montado como quedaría desde nuestra computadora basta con dar el siguiente comando en la terminal (recordemos estar situados en nuestro directorio principal, en este caso /path-to/pelicano/):

   pelican --listen

Nos dará la dirección para desplegar nuestro sitio en el explorador preferido (siempre desde nuestra computadora, aún no lo montamos al servidor), podemos copiar y pegar o dar clic para abrirlo. Ya podemos ver nuestro sitio como lo verán nuestros visitantes, con una sola entrada.

Nos damos cuenta que aparecen algunas partes que nosotros no escribimos, el mismo sitio nos menciona que varias de esas partes pueden ser editadas desde su config file. Podemos poner nuestras redes sociales, algunos links, escribir algunas cosas en español. Este es el tema básico de pelican, Smashing Magazine, algunas partes quedan en inglés. Más adelante podemos buscar otro tema para el sitio estático, algunos de estos temas permiten manipular más fácil los templates para ponerlos en español. No tiene mucho sentido manipular los archivos html del directorio output/ pues justo la idea es no tener que manejar mucho html, y de ser necesario hacerlo desde una template para que sea generalizado, pero pueden alterarlos si saben bien lo que hacen.

El sitio aún está bastante árido, incluso pueden pasar de esos arbustos rodantes del desierto. Para ponerle sabor podemos añadir los directorios /path-to/pelicano/content/pages y /path-to/pelican/content/images. Dentro de pages/ es posible crear archivos markdown de los sitios permanentes: uno donde digamos de que trata el sitio, otro que diga quienes son, una lista de nuestras redes sociales, unas ligas a este nuestro sitio favorito, como gustemos armar el sitio. Incluso si no deseamos hacer un blog podemos manipular un poco las cosas para hacer un sitio permanente.

En images/ guardamos las imágenes que usaremos para nuestras publicaciones. Si el nuestro será un blog dedicado al trabajo fotográfico aquí podemos guardar las fotos e incluso hacer subcarpetas para tener todo bien ordenado. Debemos dar la ruta correcta al agregar las imágenes en la publicación.

Estilos para el sitio

De esta introducción rápida ya tenemos un sitio con un estilo que se ve bien. Pero lo relevante siempre es poder manejar el estilo para ponerlo como queramos. Para ver posibles temas para el sitio visitamos:

https://github.com/getpelican/pelican-themes

Si estos temas no son convincentes, podemos usarlos de plantilla y manipularlos con jinja, quizá en un futuro compartamos algo al respecto (muchos planes a futuro :P).

Lo dejo así por el momento, en próximos días les comparto como subirlo a codeberg.