/home/lucio.albenga.es

🇪🇸 ES | 🇬🇧 EN

Como crear y publicar tu sitio web con Emacs y Org Mode

Hace tiempo que están bastante de moda los generadores de sites estáticos para crear un sitio web y en general estos generadores usan Markdown como lenguaje de marcas para generar el contenido html del sitio web.

Muchos usuarios de Emacs utilizamos Org Mode en nuestro día a día y la verdad es que una vez que te has acostumbrado a usarlo es una gozada de utilizar así que ¿por qué no usarlo también para crear el contenido de nuestro sitio web?

En este howto vamos a ver cómo utilizar el generador de sites estáticos Pelican para crear un sitio web con documentos de Org Mode en Emacs. Quiero dejar claro que no es el objetivo de este howto el explicar todas las características, funcionalidades y configuraciones posibles con Pelican, para eso te recomiendo que utilices su documentación1 que además es bastante buena y completa.

Doy por hecho de que ya sabes qué es Emacs y qué es Org Mode y que además sabes utilizar ambos. De hecho si estás leyendo esto es porque probablemente seas usuario habitual de Org Mode.

Instalando Pelican y creando nuestro sitio base

Lo primero que debes hacer es descargar e instalar Pelican. En mi caso yo lo hago con virtualenv (puedes consultar otros métodos de instalación en el sitio web de Pelican 2), abro una terminal, voy a la ruta donde guardo mis entornos virtuales y luego ejecuto lo siguiente: 

virtualenv pelican              # crea el entorno virtual
source pelican/bin/activate     # activa el entorno
pip install pelican             # instala Pelican

Si no tienes virtualenv en tu sistema seguro que está en el repositorio de paquetes de tu distribución de GNU/Linux. Si usas otro sistema consulta la documentación oficial de virtualenv3.

El entorno virtual seguirá activo en esta terminal hasta que ejecutemos el comando deactivate. No ejecutes el comando porque necesitamos el entorno para ejecutar los siguientes pasos.

Ahora que ya tenemos Pelican instalado y funcionando seguimos los pasos del inicio rápido para crear nuestro sitio web: 

mkdir -p /ruta/local/del/proyecto/nuestra-web   # creamos una carpeta para nuestro proyecto web
cd /ruta/local/del/proyecto/nuestra-web         # entramos en la carpeta
pelican-quickstart                              # ejecutamos el inicio rápido

Durante el proceso de inicio rápido Pelican nos hará una serie de preguntas para configurar el proyecto de nuestro sitio web. Las respuestas probablemente serán distintas para tu caso pero, para que te hagas una idea, esto es lo que nos va a preguntar con unas posibles respuestas de muestra: 

> Where do you want to create your new web site? [.] 
> What will be the title of this web site? Mi Sitio Web
> Who will be the author of this web site? yomismo
> What will be the default language of this web site? [es] 
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) https://misitio.com
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Rome] 
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost]
> What is the port of your SSH server? [22] 
> What is your username on that server? [root] user
> Where do you want to put your web site on that server? [/var/www] 
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) N

De momento podemos ejecutar el comando deactivate y salir del entorno virtual ya que tenemos varias cosas que hacer antes de que nos haga falta de nuevo.

Configurando Pelican para Org Mode

Para nuestro objetivo necesitamos el plugin org_reader4, así que vamos a obtener los plugins de Pelican. La forma más rápida de obtener los plugins es descargarlos desde su repositorio en GitHub5 y ponerlos en la carpeta que queramos. Ya le indicaremos a Pelican la ruta a esa carpeta en el siguiente paso. Para ello vamos a la carpeta dónde queramos descargar los plugins y ejecutamos el siguiente comando: 

git clone --recursive https://github.com/getpelican/pelican-plugins

Una vez que tenemos los plugins, procedemos a configurar Pelican para que use el plugin org_reader que es la pieza fundamental para generar nuestro sitio web a partir de archivos *.org de Org Mode.

Abrimos el archivo pelicanconf.py y le añadimos lo siguiente justo al principio: 

import os # esta línea ya está en el archivo

PLUGIN_PATHS = ["/ruta/a/la/carpeta/donde/están/los/plugins/de/pelican"]
PLUGINS = ["org_reader"]

En el caso de que tengamos una instalación de Emacs en una ruta distinta a las habituales también añadimos la siguiente línea: 

ORG_READER_EMACS_LOCATION = "/ruta/al/ejecutable/de/emacs"

Añadiendo coloreado de sintaxis

Para mi sitio web me faltaba una cosa importante que era añadir el coloreado de sintaxis para las publicaciones que, como esta, contienen código fuente. Así que tras buscar di con el sitio web de Anten Linevich6 donde solucionaba el problema creando un export backend personalizado.

Para hacer esto mismo volvemos a abrir nuestro archivo pelicanconf.py y añadimos lo siguiente: 

ORG_READER_EMACS_SETTINGS = os.path.abspath("lisp/pelican-html.el")
ORG_READER_BACKEND = "'pelican-html"

Ahora vamos a crear nuestro backend personalizado pelican-html siguiendo estos pasos:

  1. Creamos en el raíz de nuestro proyecto web la carpeta lisp/. Podemos llamarla como queramos pero debe coincidir con lo que hemos definido en la constante ORG_READER_EMACS_SETTINGS de arriba.

  2. Dentro de esa carpeta creamos el archivo pelican-html.el y dentro del mismo ponemos lo siguiente: 

       ;; Este código es (c) 2017 Anten Linevich y está licenciado bajo 
   ;; Creative Commons Attribution 4.0 Internacional License
   ;; https://linevi.ch/en/org-pygments.html

   (require 'org)
   (require 'ox)
   (require 'ox-html)

   (org-export-define-derived-backend 'pelican-html 'html
     :translate-alist '((src-block .  pelican/pygments-org-html-code)
                        (example-block . pelican/pygments-org-html-code)))

   (defvar pygments-path "pygmentize")

   (defun pelican/pygments-org-html-code (code contents info)
     "Process code block with Pygments See http://pygments.org/ for details"

     ;; Generate temp file path by hashing current time and date.
     (setq temp-source-file(
          format "/tmp/pygmentize-%s.txt"(md5 (current-time-string)))
     )
     ;; Writing temp file
     (with-temp-file temp-source-file (insert (org-element-property :value code)))
     ;; Processing
     (shell-command-to-string (format "%s -l \"%s\" -f html %s"
                                      pygments-path
                                      (or (org-element-property :language code)
                                          "")
                                      temp-source-file)))

   (provide 'pelican-html)
  3. Guardamos el archivo y ya lo tenemos todo listo para que nos haga el coloreado de sintaxis.

Escribiendo nuestra primera publicación

Vamos a escribir nuestra primera publicación para ver una plantilla básica que nos será muy útil a la hora de crear nuevas publicaciones.

Hay un montón de propiedades, metadatos en la jerga de Pelican, que podemos usar para "configurar" una publicación. Aquí solamente aparecen las que yo considero más habituales y/o importantes. Para verlas todas puedes ir a la documentación de Pelican y del plugin org_reader (ver notas al pie).

Dentro de la carpeta content/ de nuestro sitio Pelican vamos a crear un archivo hola-mundo.org con el siguiente contenido: 

#+TITLE: ¡Hola Mundo!
#+DATE: 2024-05-24
#+AUTHOR: admin
#+LANGUAGE: es
#+CATEGORY: Programación
#+PROPERTY: LANGUAGE es
#+PROPERTY: SLUG hola-mundo
#+PROPERTY: SUMMARY Este es el resumen de la publicación
#+PROPERTY: SUMMARY+ que puede ir así en varias líneas
#+PROPERTY: TAGS programación, c

A continuación vamos a ver el código fuente del programa Hola Mundo en C.
#+BEGIN_SRC c
  #include <stdio.h>
  int main(void)
  {
          printf("¡Hola Mundo!");
          return 0;
  }
#+END_SRC


#+BEGIN_EXPORT html
<hr>
<center><small>
Y esto es un bloque HTML a modo de muestra.
<p>
<a href="https://creativecommons.org/licenses/by-nd/4.0/legalcode.es">Licencia Creative Commons Atribución-SinDerivadas 4.0 Internacional (CC BY-ND 4.0)</a>
</p></small>
</center>
<hr>
#+END_EXPORT

A continuación una breve descripción de las propiedades/atributos del documento:

  • #+TITLE: ¡Hola Mundo! es la única propiedad obligatoria.
  • #+DATE: 2024-05-24 la fecha del documento puede ser una fecha en formato iso (como en el ejemplo) o un timestamp de Org Mode.
  • #+AUTHOR: admin el nombre del autor
  • #+LANGUAGE: es el idioma en el que está el documento para Org Mode
  • #+CATEGORY: Programación categoría de la publicación
  • #+PROPERTY: LANGUAGE es el idioma en el que está el documento para Pelican
  • #+PROPERTY: SLUG hola-mundo si no se especifica es el nombre del archivo *.org de la publicación
  • #+PROPERTY: SUMMARY resumen de la publicación
  • #+PROPERTY: TAGS programación, c las etiquetas que queramos ponerle

Aparte de las propiedades que se ven en el ejemplo hay una que a mi me parece fundamental, la de estado, #+PROPERTY: STATUS. Esta propiedad puede tener los siguientes valores:

  1. published (publicado): es el estado por defecto aunque no lo pongamos.
  2. draft (borrador): las publicaciones se guardan en la carpeta drafts/ del sitio web y no están enlazadas en ningún sitio.
  3. hidden (oculto): las publicaciones no aparecen enlazadas en ningún sitio y para acceder a ellas hay que conocer el enlace exacto.

Por lo tanto si queremos tener una publicación oculta añadiríamos esta etiqueta: 

#+PROPERTY: STATUS hidden

Previsualizando y publicando nuestro sitio web

Ha llegado la hora de la verdad, de ver los resultados de todo el trabajo que hemos hecho, comprobar si todo funciona y ver como generar y publicar nuestro nuevo sitio web.

Desde la carpeta de nuestro proyecto web hacemos lo siguiente:

  1. Volvemos a activar el entorno virtual: 

       source /ruta/a/nuestro/virtualenv/pelican/bin/activate

  2. Ponemos en marcha la previsualización del sitio: 

       make devserver

    Si nos fijamos, el comando anterior nos devolverá, entre otras cosas, lo siguiente: 

       Serving site at: http://127.0.0.1:8000 - Tap CTRL-C to stop

    Así que copiamos y pegamos la url http://127.0.0.1:8000 en nuestro navegador favorito para poder ver nuestra web.

    Este modo, devserver, regenera automáticamente nuestro sitio web con cada cambio que hacemos en nuestro archivo *.org por lo que siempre podremos ver los cambios recargando nuestro navegador.

  3. Salimos del modo devserver pulsando las teclas CTRL-C y si queremos publicar nuestro sitio web ejecutamos: 

       make rsync_upload

    Este comando volverá a generar todo el sitio y lo subirá a dónde le hayamos indicado cuando hicimos la configuración inicial en el inicio rápido. Si por cualquier motivo no funciona o no existe esta opción, abre el archivo Makefile en el raíz de tu proyecto web y al final del mismo deberían de aparecer todas las opciones disponibles para subir tu sitio web al hosting (ssh_upload, sftp_upload, etc.).

Siguientes pasos

En este howto hemos dado los primeros pasos para crear un sitio web con Pelican y gestionar sus contenidos escribiéndolos con Emacs y Org Mode. Ahora es el momento de profundizar con Pelican para crear tu sitio web a tu gusto así que utiliza la documentación de Pelican y busca un tema7 que te guste para tu web, o crea el tuyo propio.

Agradecimientos

Quiero darle las gracias a BxCx del canal #emacs-es en Libera.chat8 ya que la idea de este howto surgió porque estando en el citado canal empezó a hablar del tema de cómo crear un sitio estático con Emacs y me estuvo preguntando sobre cómo estaba hecho este sitio.

También quiero darle las gracias a Anten Linevich porque sin su publicación no habría dado con la tecla para poner el coloreado de sintaxis.

Copyright

Este artículo es Copyright © 2024 Lucio F. Albenga y está bajo Licencia Creative Commons Atribución-CompartirIgual 4.0 Internacional (CC BY-SA 4.0)

El código del ejemplo/archivo pelican-html.el es Copyright © 2017-2024 Anten Linevich y está bajo Licencia Creative Commons Attribution 4.0 Internacional License