Enredando con Gitlab para montar una página web estática con NodeJS

Hace tiempo que tenía ganas de enredar con el sistema de integración continua de Gitlab. Para quien no este puesto, Gitlab es un servicio Git alternativo a GitHub, solo que libre en su totalidad. Podéis compararlo con el producto de WordPress en el sentido de que puedes tener tu espacio en la versión .com, o bien descargarte el código y montarte tu propia versión en tu propia maquina, modificándolo al gusto. El extra de Gitlab, además de las virtudes del software libre, y de que Microsoft no lo controle, es que trae su propio sistema de integración y despliegue, por lo que no necesitas utilizar una tercera parte: puedes hacer que al subir tu código se realicen las pruebas, preparen informes, y lo despliegue mediante un contenedor (tecnología docker o kubernetes, al gusto).

Mi proyecto para este caso era generar una página web estática, un pequeño blog en Hexo que transforma archivos en notación markdown a HTML. Hay otras alternativas, pero tenía ganas de actualizar mis conocimientos de maquetación de NodeJS, ya que en mi vida laboral tiendo a utilizar versiones obsoletas para corregir errores de aplicaciones con un tiempo. Para crearlo usé las siguientes herramientas:

• Git: control de versiones creado por Linus Torvalds.
• NVM: para gestionar las versiones de NodeJS instaladas en mi sistema y poder alternar entre ellas a gusto. Hay un instalador para Windows.
• VSCodium: una versión construida del código abierto de Visual Studio Code para manejar el código más cómodamente. Si leéis la licencia veréis que al compilarlo Microsoft añade sus extras de telemetría los cuales no están en la parte abierta, y yo estoy encantada de haber encontrado un proyecto que me ahorre el esfuerzo de compilarlo a mano para no tener que sufrir la parte turbia.

Nota: Me gusta bastante trabajar desde consola, pero obviamente podéis usar el gestor de terminal o la interfaz gráfica de Git que más os guste (Sourcetree, Smartgit, Gitkraken). Todas son opciones muy dignas pero ninguna realmente libre, de ahí que mi explicación vaya directamente sobre terminal.

¡Pues manos a la obra! Lo primero fue colocar la versión de NodeJS a la última estable y comprobar que está correctamente instalada. Desde terminal sería:

nvm install
nvm list

Lo siguiente generar el proyecto git en Gitlab y clonármelo en mi local.

git clone https://gitlab.com/usuario/code-notepad

Tras eso pasaría a instalarme Hexo vía npm, el gestor de paquetes por defecto de NodeJS.

npm install hexo-cli -g

Y con esto entramos en el maravilloso mundo de Hexo. Lo primero es crear un blog.

hexo init blog
cd blog
npm install

Si queremos almacenar imágenes propias en los artículos que escribamos, tendremos que habilitar la creación de una carpeta con esa función. Esto se puede hacer valor el valor del fichero _config.yml que marca esto a cierto.

post_asset_folder: true

Y probamos que todo funciona como esperamos, desplegándolo mediante un único comando haciendo click en la dirección URL que nos devuelve el terminal.

hexo server

Después podemos instalar algún tema. Hay un repositorio estupendo, y es tan fácil como descargar y colocarlo en la carpeta themes.

Yo en particular soy una fanática de los diagramas de flujo de mermaidJS, que me permiten completar mis notas de programación con gráficos. De ahí que añadiese el plugin correspondiente vía npm.

npm i hexo-filter-mermaidjs

Y luego lo configurase en los 2 siguientes pasos.

1. En la sección de plugins de _config.yml añadí:

# mermaid chart 
mermaid: ## mermaid url https://github.com/knsv/mermaid 
  enable: true  # default true 
  version: "7.1.2" # default v7.1.2 
  options: 
    #startOnload: true  // default true

2. Al final de footer.ejs de la plantilla del tema a usar, añadí:

<% if (theme.mermaid.enable) { %>
  <script src='https://unpkg.com/mermaid@<%= theme.mermaid.version %>/dist/mermaid.min.js'></script>
  <script>
    if (window.mermaid) {
      mermaid.initialize({theme: 'forest'});
    }
  </script>
<% } %>

Por último queda añadir el fichero de integración continua añadiendo en la raíz un fichero .gitlab-ci.yml. Este fichero usará un contenedor docker con una imagen de NodeJS 10.15.3, donde instalará Hexo, contruirá los paquetes, generará la la página y la desplegará en Gitlab pages el contenido de la rama master él solito.

image: node:10.15.3
 
cache:
  paths:
    - node_modules/
 
before_script:
  - npm install hexo-cli -g
  - test -e package.json && npm install
  - hexo generate
 
pages:
  script:
    - hexo generate
  artifacts:
    paths:
      - public
  only:
    - master

Con esto tenemos el esqueleto listo: a subir el código a Gitlab, y tras esto cualquier subida lanzará la integración continua, dejando como resultado la página lista en la dirección “tuUsuario.gitlab.io/code-notepad”.

git commit -a -m "Base del sistema"
git push

Así que a generar un primer artículo desde el interior de la carpeta source. Desde aquí podemos ir escribiendo los artículos en sintaxis markdown.

cd source
hexo new post "primer articulo"

Esto nos genera un fichero en sintaxis Markdown con la siguiente cabecera. Los valores cambiamos al gusto para que se ajusten a lo que deseemos en nuestro blog para título, fecha, y etiquetas para ordenar el contenido:

---
title: primer artículo
date: 2018-04-17 10:00:00
tags: [Etiqueta1, Etiqueta2]
---

Podemos colocar las imágenes en la carpeta homónima (en este ejemplo «mi primer artículo»). Para referenciar las imágenes usamos la siguiente sintaxis:

{% asset_img "imagen.jpg" "Descripción de la imagen" %}

Y con esto ya estamos listos, commit y push en cuanto estemos listos, y Gitlab pages se encargará de publicarlo por sí solo. ¿No está mal, eh?