ENTRE DRAGONES Y PINGÜINOS

Crónica de una migración de Wordpress a Hexo

27 de mar. de 2024 - #Informática

Hace tiempo que se habian acumulado un buen puñado de cosas en WordPress que no me agradaban. Por ello me planteé que debería ser capaz de poder llevarme el contenido, que no era poco, a otro lugar si las cosas se torcían hasta alcanzar un punto inaceptable. Ha sido un trabajo de muchos meses, ¡porque tenía más de 10 años de contenido que revisar para esa posible migración! Decidí documentar toda esta experiencia para que en caso de que alguien más se encuentra en una situación similar, que no tenga por qué partir de cero.

Por un lado quería algo que mi nueva solución pudiese mantener con facilidad, que fuese sencillo llevársela de un servidor a otro, que no dependiese de una tercera parte para recuperar el contenido… y a ser posible, que ocupase poquito espacio. Por esa razón opté por un generador de web estático: era una cantidad grande información a mover y debía intentar que el sistema tuviese poca complejidad. Si hubiese sido una cantidad menor de artículos, quizás me hubiese planteado otra cosa, pero jugamos con las cartas que nos han tocado.

El primer paso era elegir un sistema de blog estático, y me decanté por Hexo. Mi criterio principal fue que Hexo está escrito con NodeJS, que es una tecnología que domino. Sé que Hugo es una plataforma excelente, pero desgraciadamente no controlo el lenguaje de programación Go tanto como para manejar la plataforma totalmente a mi antojo. Ambos sistemas permiten procesar ficheros en Markdown (texto plano con extensión .md), que es una forma muy natural de tomar notas facilitando mucho el proceso de escritura. Además, ambas opciones pueden generar de forma automática las páginas de índice, categorías y “nube de etiquetas”, quitándote todo el trabajo duro que hay detrás de esas herramientas de navegación de blogs que a día de hoy se suelen dan por sentadas, pero su manteniemiento adecuado requiere muchísimo tiempo.

Así que una vez decididas las herramientas, me puse manos a la obra.

Montaje paso a paso

Aviso: empleo comandos de terminal, esa herramienta que en el imaginario general consiste en una espeluznante pantalla negra con texto blanco (o verde fósforo, porque Matrix ha influído mucho en la cultura moderna). Era eso o morir, porque estaba moviendo muchísimo contenido. No os asustéis porque explicaré para qué sirve cada comando, y la mayoría de ellos sólo los tendréis que emplear una única vez durante el montaje.

1. Instalar NodeJS y Hexo

Primero debemos instalar NodeJS, preferentemente la última versión LTS (la versión estable con soporte más duradero) que podéis encontar en la página oficial. Se trata de una plataforma que permite manejar código JavaScript sin tener que preocuparnos de las particularidades de cada navegador, que nos quita muchos dolores de cabeza a los programadores. A continuación, procedemos a instalar Hexo mediante el gestor de paquetería por defecto de NodeJS (que se llama muy originalmente npm, las siglas de Node Package Manager o “Gestor de Paquetes de Node”) desde el terminal con un sencillo comando.

1
npm install -g hexo

2. Exportar el contenido de WordPress

  1. Desde el panel de WordPress.com (Dashboard) fui a Herramientas → Exportar. Desde alli , en Exportar contenido seleccioné Exportar todo. Aquello me entregó un fichero .zip', que al descomprimirlo contenía un fichero llamado export.xml, fundamental para este proceso.

  2. A la hora de elegir una herramienta de migración válida, me decidí por el modulo de Hexo llamado hexo-migrator-wordpress. Usarlo es tan sencillo como abrir un terminal, ir a la ruta donde descomprimí el fichero de exportación de WordPress, y proceder con la instalación de la herramienta de migración en ese espacio. De nuevo empleé los comandos para instalar, y lo dejé a lo suyo durante el buen rato que duró la migración.

    1
    2
    npm install -g hexo-migrator-wordpress
    hexo migrate wordpress export.xml

  3. Hacer una revisión rápida de los ficheros resultantes, para ver qué ha ido bien, y qué no.

3. Armar una instancia de Hexo rápidamente en local

Por comodidad, reutilicé la estructura de Hexo que tengo guardada como proyecto en GitLab, sobre la que están basadas mis notas de código y también la PWA de YSYSTEM. Si vas a empezar desde cero con Hexo, te gusta que los bloque de código en tus artículos lleven coloreado sintáctico, y puedes necesitar representar algún diagrama con MermaidJS, este proyecto ya lo lleva todo preparado “de serie”. Partiendo de esa base, el proceso se reduce a:

  1. Descargar el contenido de ese repositorio en mi equipo local, que es tán fácil como ir a Code → Download source code → zip.

  2. Descomprimir ese fichero .zip (recomiendo hacerlo en un directorio nuevo, para evitar confusiones), e ir al directorio (o carpeta, si sois de Windows) source\_posts. Allí fueron eventualmente el montón de ficheros .md que me devolvió el sistema de migración.

  3. Instalar el proyecto. Es tan sencillo como volver al directorio raiz del proyecto (donde está el fichero llamado package.json) y emplear el comando de terminal de instalación (que generará una carpeta llamada node_modules con las herramientas necesarias):

    1
    npm install

  4. Lanzar Hexo en un servidor local para una primera prueba. No os asusteís, que NodeJS y Hexo lo manejan todo automágicamente en un único comando de terminal (recuerda, “S” de “servidor“. Utilizarás mucho este comando cuando te plantees realizar cambios estéticos para verificar que todo va como esperabas):

    1
    hexo s

  5. Aquello devolvió una dirección web en localhost y le di un primer tiento: más o menos aquello funcionaba, pero el formato dejaba que desear, y debía corregir todos los enlaces a fotografías a una sintaxis correcta en Markdown. Esta fue la parte que me ha consumido más tiempo: dejar todos los artículos migrados en un formato correcto, bien etiquetados. Aproveché la oportunidad de esta relectura para actualizar algunos enlaces y anotar los detalles que se habían quedado obsoletos.

  6. Para apagar el servidor local, se hace desde el terminal con la combinación de teclas Ctrl + C (recuerda, “C” de “cancelar”). Si tu terminal está en una ventana, cerrar el terminal tambien lo apaga.

4. Configuración personal básica

Obviamente no quieres que mantener los datos de mi web de demostración, ¡quieres preparar tu propio sitio! En el fichero _config.yml te interesarán principalmente las siguientes opciones:

El tema configurado por defecto en el código que os he compartido es “Next”, que lleva el añadido del soporte de diagramas. La configuración de este tema en concreto se maneja desde el fichero _config.next.yml.

5. Manejar las entradas en Hexo

Los detalles más importantes para publicar tus artículos, y lo que verdaderamente será tu día a día si usas Hexo, son los siguientes:

  1. Los ficheros Markdown para Hexo comienzan con unas líneas de cabecera donde se ubican los metadatos de dicha entrada. Entiende que son como un custionario que debes rellenar para que la página se catalogue bien. En general los nombres de cada campos nombres son bastante descriptivos, y el único que merece la pena puntualizar es el campo thumbnail, con el que podemos indicarle la ruta de la imagen con la que deseemos generar la “vista de tarjeta” cuando se comparta un enlace a esta entrada desde un medio externo. Por ejemplo, se compartimos el enlace de esa publicación en concreto en Mastodon, tiene a aparecer un recuadro con el nombre la página, nombre del artículo, y una imagen: aquí es donde decides cuál es esa imagen. Aviso que en la configuración que os he compartido, si no escribimos la línea en la que se especifica este campo, se seleccionará el logotipo del sitio web de forma automática.

    1
    2
    3
    4
    5
    6
    7
    8
    ---
    title: 'Este es el título del post'
    date: 2024-03-27 10:00:05
    categories: [Categoria1, Categoria2]
    tags: [Etiqueta1, Etiqueta2]
    thumbnail: '/images/thumbnail.png'
    excerpt: 'Breve resumen de la publicación'
    ---

  2. Las imágenes del artículo (u otros recursos relacionados con él) deben almacenarse en un directorio con el mismo nombre del artículo (obviamente sin la coletilla .md), para que el enlace entre el fichero Markdown y el recurso sea directo.

  3. Los artículos a publicar son ficheros Markdown que se almacenan el directorio source/_posts. Se puede crear el esqueleto de un nuevo artículo para publicar mediante el comando de terminal hexo new post "nombre-del-post". En la configuración que he compartido, este comando genera además del artículo la carpeta para las imágenes asociadas.

  4. Los artículos en borrador son ficheros Markdown que se almacenan el directorio source/_drafts. Se puede crear el esqueleto de un nuevo borrador mediante el comando de terminal hexo new draft "nombre-del-post".

  5. Si se quiere pasar un borrador a publicación, es tan fácil como moverlo (junto a la carpeta homónima con las imágenes relacionadas) desde el directorio _drafts al directorio _posts. Para “despublicar”, podemos realizar la acción contraria.

  6. Lanzando el comando de terminal hexo generate se genera tu sitio web estático dentro de una carpeta public, quedando listo para que lo pongas en el servidor real que desees. Se puede abreviar este comando como hexo g.

6. Reducir peso de la web

Decidí crear un tema de Hexo a medida para la ocasión basándome en el de Bear, porque mi intención era desde un principio no depender de nadie: no quiero ningún enlace a ficheros CSS o Javascript de terceros (cosa que hacen la mayoría de los temas de la galería de Hexo ¡y puede tener sentido si quieres cosas bonitas!), sino algo que esté al 100% bajo mi control y sin sustos. Si queréis usarlo, podéis descargarlo y colocarlo dentro del directorio themes de la estructura de Hexo. Los detalles del mismo dan para otra entrada, por lo que los dejaré para la semana que viene. La configuración a grandes rasgos consiste en cambiar la configuración dentro del fichero _config.yml del propio tema para que los detalles sean los propios del propietario del sitio (nombre del autor, nombre del sitio, descripción del sitio, enlaces de contacto, logotipo del sitio…), y con solo eso lo tenéis listo.

Cuando añadí las imágenes, las reduje en peso empleando Squoosh, y opté por usar el formato .jpg. También utilizo algún .png excepcional cuando quiero manejar alguna transparencia, como es en el caso del logotipo de la página. Soy consciente de que el formato moderno .webp de Google es cada vez más ubicuo, pero no es interpretable desde cualquier navegador y sistema operativo, y es propenso a tener vulnerabilidades graves de seguridad. En 2023 hubo 0-day con explotación relacionado con él (en lenguaje vulgar, un problema de seguridad grave ante el cual lo único que puedes hacer es puede llorar, porque hay gente con intenciones poco honorables que lo utiliza activamente para causar daño, y no hay ninguna solución disponible para tu sistema) y por esa razón, su descarga y reproducción está bloqueada en muchos dispositivos y entidades: por radical que suene, es mejor bloquear un cierto formato de imagen que arriesgar la integridad de tu dispositivo (al cual posiblemente Google no le de un soporte por razones de obsolescencia programada). Teniendo en cuenta de que uno de los objetivos de esta versión de mi blog era que el contenido se pudiese leer íntegramente en la mayor cantidad de dispositivos posibles siendo seguro, tomé la decisión de no usar dicho formato, sin importar cuánto insista Google en ello.

Al final de este proceso, cuando lanzo hexo generate, el sitio completo con más de 10 años de información acumulada se queda en menos de 40MB, mientras que todo el HTML de Wordpress ocupaba entorno a 500MB (y eso sin contar la infraestructura de base de datos que llevaba detrás). Puedo decir que me siento tremendamente orgullosa del ahorro logrado.

7. Publicarlo en un servicio web

Inicialmente intenté publicar el sitio en neocities.org, pero acabé baneada (me han prohibido el acceso) y hasta ahora sigo sin recibir respuesta a mis intentos de comunicación con el soporte del sitio. Intuyo que no les gustó que mis subidas fuesen tan intensas con tanto fichero pequeño seguido. Reconozco haber subido 11 años de publicaciones en un espacio de tiempo muy corto, y esa “ametralladora de subidas” pudo hacer saltar alguna alarma por su lado, lo que podría ser razonable. A estas alturas doy la batalla de recuperación del acceso por perdida.

En consecuencia activé mi plan B, usando GitLab Pages, lo que tiene algunas ventajas: es una solución única para control de versiones de código que me ofrece un servidor para páginas estáticas. Si GitLab se pusiese tonto a futuro, pues lo puedo mover literalmente 15 minutos de reloj a otro lugar.

Ante todo quiero señalar que las páginas que se generan con Hexo se pueden alojar prácticamente en cualquier servidor con muy poca complicación, porque es copiarlas a un directorio remoto y poco más. Solo hay que asegurarse de cambiar la URL en el fichero config.yml ajustándola al nuevo lugar donde se almacenará, relanzar el generador de Hexo (hexo g en terminal), y disfrutar del resultado en la carpeta public. Así nació “Entre dragones y pingüinos. Bitácora de Angeles Broullón.” en la versión disponible desde gitlab.io: en este nuevo sitio ligero se puede encontrar todo el contenido que existía en “Angeles’ blog: Cuaderno de una programadora” de WordPress, en su nueva encarnación baja en colesterol 😉.

Resumen simple del “uso de diario” de esta solución

En última instancia, todo se reduce a:

⬆ , , , ,