Requisitos

• Cuenta de GitLab
• R, Rstudio y Git instalados en la máquina local
• Pandoc instalado
• Paquetes Blogdown, Rmarkdown, Knitr y otros paquetes que se requieran para los contenidos, instalados.

Paso 1: Repositorio de GitLab

GitLab tiene un servicio que se denomina GitLab Pages. Se trata de un servicio que ofrece la posibilidad de desplegar una página web estática mediante una diversidad de programas servidor como Hugo server. GitLab Pages ofrece runners para páginas de repositorio, usuario o grupo, pero el proceso que describiré a continuación no difiere uno de otro.

REspacialEs en GitLab también es un grupo de usuarios para el cual creamos este sitio web. Entonces vamos a iniciar creando un repositorio nuevo que tendrá como estructura el nombre del grupo como subdominio del dominio de GitLab Pages esto sería así: “rspatial_es.gitlab.io”

Y ahora vamos a configurar este repositorio como privado, pero con la sección Pages como público. Esto sería así:

Paso 2: Clonar repositorio y crear proyecto de Rstudio

El repositorio está vacío y solo contiene, posiblemente, el fichero README.md donde estará una descripción del repositorio. Este no es importante por ahora. Vamos a aprovechar una ventaja de Rstudio, para crear un proyecto de Rstudio a partir de un repositorio con control de versiones. Usando el asistente para crear proyectos, damos clic en nuevo proyecto -> Control de versiones -> Git y escribimos la URL del repositorio, en este caso https://gitlab.com/rspatial_es/rspatial_es.gitlab.io. El nombre del directorio para el proyecto se va a escribir automáticamente, pero se puede cambiar con cualquiera que se desee. Yo lo dejé así por defecto. Y dentro de mi ruta de predefinida para desarrollo.

Paso 3: Elegir el tema de Hugo que se quiere usar.

GitLab Pages permite desplegar páginas web directamente desde HTML o mediante un servidor usando otro lenguaje marcado (por ejemplo markdown). En este caso usaremos hugo server para desplegar contenido que escribiremos en md o Rmd desde Rstudio. Para ello, lo primero que haremos es escoger entre los cientos de opciones un tema que más se ajuste a nuestras necesidades. Hay muchas opciones y por eso hay que ser cautelosos a la hora de elegir. Para empezar podemos explorar los Temas para hugo disponibles en el sitio oficial. Aquí podremos ver los temas con demos y los enlaces al repositorio correspondiente.

En nuestro caso se ha elegido el tema hugo-future-imperfect-slim adaptado por Patric Collins a partir del tema hugo-future-imperfect de Julio Pescador.

Aprovecho para agradecer su tan dedicado trabajo y por ponerlo a disposición de forma abierta.

Paso 4: Crear la estructura básica de blogdown

En este paso vamos a usar el paquete blogdown para ayudarnos y montar una estructura básica del blog con el tema elegido. Empezaremos por cargar la librería en la sesión de R mediante library(blogdown) y luego llamar a la función new_site() con algunos argumentos para crear la estructura. Pero antes hay que fijarse qué versión mínima de Hugo server requiere el tema para estar seguros de que funcionará. En nuestro caso lo podemos ver en el fichero theme.toml del repositorio, donde especifica min_version = "v0.62.0/extended"

library(blogdown)
blogdown::install_hugo() # instalará la versión extendida más actual 
new_site(theme = "pacollins/hugo-future-imperfect-slim", # repositorio github del tema
         empty_dirs = TRUE, # mantener todas los directorios incluidos los vacios 
         to_yaml = TRUE, #Importante! Asegurarse convertir a YAML 
         install_hugo = FALSE # En nuestro caso para evitar un error.
         ) 

Como se puede ver, hemos instalado Hugo server por separado porque al momento de instalar automáticamente con la función new_site() genera un error porque no puede comprobar la versión mínima declarada en el tema.

Paso 4 (alternativa): Crear la estructura básica de blogdown de otra manera

Esta es la forma que he elegido para nuestro blog por una sola razón. Permitirá tener actualizada la versión del tema, según cómo los desarrolladores vayan actualizando el repositorio. Con el repositorio en el estado del paso 3, en el terminal del sistema ejecutaremos:

# ubuntu o debian
sudo apt install hugo-extended
mkdir themes # crea un directorio themes
cd themes # Apunta el espacio de trabajo en el directorio themes
git submodule add https://github.com/pacollins/hugo-future-imperfect-slim.git
cd .. 
cp -R themes/hugo-future-imperfect-slim/exampleSite/* .

En el caso de que uses Windows, te recomiendo hacer manualmente los tres pasos:

1. Instalar hugo-extended
2. Crear el directorio themes dentro del directorio del proyecto
3. Clonar como submódulo el repositorio del tema dentro del directorio themes
4. Copiar todos los directorios y ficheros de la carpeta exampleSite a la raíz del proyecto.

Paso 5: Configuración del sitio

Ya en este estado es necesario que se configure el fichero config.toml. En este paso se definirán parámetros tanto para Hugo server como para el comportamiento del sitio web. También el sitio oficial explican en qué consisten cada una de los parámetros y su uso, pero te voy a recomendar que visites el libro de blogdown en línea. En este sitio hay una explicación muy detallada de estas configuraciones. Además el propio tema elegido tendrá indicaciones de los parámetros fijados para el tema. Por ejemplo: Wiki del tema hugo-future-imperfect-slim.

Paso 6: Integración continua / despliegue continuo (CI/CD)

La configuración para Integración y Despliegue continuo del blog se debe especificar en formato YAML en el fichero .gilab-ci.yml. Este fichero detectará GitLab CI/CD y ejecutará automáticamente las acciones especificadas. A continuación detallo el contenido de este fichero, pero no sin antes mencionar que más información se puede encontrar en el sitio oficial de GitLab Pages:

• image: Ya que se trata de un blog para asuntos espaciales con R se ha elegido la imagen versionada más reciente de rocker/geospatial. Las versiones Rocker están basadas en Ubuntu LTS en lugar de Debian. Y al momento se encuentran actualizadas a Ubuntu 20.04.

image: rocker/geospatial:latest

• variables: Variable git para sincronizar la última versión del submódulo del tema Hugo desde el repositorio original. Se usa una variable de GitLab denominada GIT_SUBMODULE_STRATEGY con valor recursive para que actualice todos los submódulos que pueda tener el repositorio.

variables:
  GIT_SUBMODULE_STRATEGY: recursive

• before_script Script bash para ejecutar antes de compilar los ficheros del blog. En esta parte se debe especificar todas las configuraciones previas requeridas por R para compilar el blog. Debido a que la imagen docker seleccionada ya tiene preinstalados algunas librerías y paquetes. Por ejemplo una actualización de librerías del sistema, instalación de pandoc o instalación de paquetes extra de R para la compilación de los posts.

before_script:
  - apt-get update && apt-get -y dist-upgrade
  - apt-get -y install pandoc pandoc-citeproc
  - R -e "install.packages(c('rmarkdown', 'knitr', 'blogdown', 'RefManageR', 'tidyverse'),repos='http://cran.rstudio.com')"
  - R -e "devtools::install_github('rstudio/fontawesome')"

• pages: El tipo de CI/CD que el la API de Gitlab debe ejecutar para proveer como servicio web. Contiene las especificaciones para el compilación del blog, ficheros disponibles para Hugo server y la rama del repositorio de donde va a copiar los ficheros para compilar.

pages:
  script:
    - R -e "blogdown::build_site()"
  artifacts:
    paths:
      - public
  only:
    - master

Esta es la configuración básica para desplegar el blog en GitLab. Existen otros parámetros de CI/CD que pueden ser aprovechados para configurar el blog, tanto en seguridad, privacidad, requerimientos básicos, etc. Pero no olvidar que las versiones gratuitas del servicio de https://gitlab.com tienen un límite de Horas de CI/CD por lo que se debe optimizar al máximo el tiempo de ejecución de los runners. Entre más configuraciones se especifican al fichero de CI/CD o a los contenidos del blog más tiempo tomará la compilación.

Paso 7: Generación de contenido y GIT

Independientemente de haber o no configurado CI/CD, se puede escribir ya contenidos para el blog. La forma rápida de iniciar una nueva entrada de blog es mediante la función blogdown::new_post(). Por ejemplo así iniciamos esta entrada de blog.

new_post(title = "Cómo se construyó este blog", 
         author = "Gabo Gaona",
         categories = "R",
         tags = c("blogdown", "tutoriales", "gitlab", "Hugo" ),
         subdir = "blog", 
         ext = ".Rmd")

Una vez que se ha escrito el contenido de la entrada de blog, se debe hacer un commit y push en el repositorio git. Inmediatamente recibido el commit, GitLab CI/CD reiniciará el runner con la consecuente tarea de reconstrucción y despliegue del sitio con los nuevos cambios.

Pasos opcionales: Personalización

En nuestro caso hemos hecho unas leves personalizaciones extra que permiten tener por ejemplo: Las fechas en formato español. Para ello basta con crear la parte de la estructura del tema que queremos personalizar y agregar ahí los ficheros.

Por ejemplo en nuestro caso hemos creado el fichero layouts/_default/date.es.html, en la carpeta raíz del proyecto. El fichero contiene un a declaración HTML para definir el formato de fecha deseado. Esto se hizo siguiendo el ejemplo para holanda:

{{- $month_names := slice "Enero" "Febrero" "Marzo" "Abril" "Mayo" "Junio" "Julio" "Agosto" "Septiembre" "Octubre" "Noviembre" "Diciembre" -}}
{{- $month := sub .Date.Month 1 -}}
{{ .Date.Day }} de {{ index $month_names $month }}, {{ .Date.Year }}

En conclusión, GitLab Pages, hugo y blogdown permiten desplegar fácilmente sitios estáticos personales, grupos de trabajo o proyectos, con pocos recursos y mucha pasión.