En esta sección se explica cómo contribuir o editar esta web estática generada con Hugo y desplegada con GitLab Pages. Existen diferentes maneras de editar la web, por lo que se exponen las diferentes formas en función de los conocimientos técnicos.
Editar desde la interfaz gráfica de una instancia de GitLab. Se requiere conocimientos básicos del lenguaje de marcado Markdown y una cuenta en la instancia de GitLab donde se aloja la página web.
Un contenido o entrada ya creada.
Crear una entrada nueva en la web. No se necesitan conocimientos técnicos.
Editar con git. Se requiere conocimientos básicos del lenguaje de marcado Markdown y una cuenta en la instancia de GitLab donde se aloja la página web. Además, se requieren conocimientos de git y quitarse el miedo a usar la terminal (aunque también existen interfaces gráficas para git :) ).
Un contenido o entrada ya creada.
Crear una entrada nueva en la web.
Editar desde el móvil con Termux y Markor. Se requiere conocimientos básicos del lenguaje de marcado Markdown y una cuenta en la instancia de GitLab donde se aloja la página web. Además, se requieren conocimientos de git y no tener miedo a una terminal.
Para seguir estos pasos, se requiere conocimientos básicos del lenguaje de marcado Markdown y una cuenta en la instancia de GitLab donde se aloja la página web.
Pasos:
En la esquina superior derecha, existe un icono a un enlace con el nombre “Editar” que dirige al GitLab donde esté alojado el código fuente de esta página web. Pinchar en el icono de editar o utilizar el atajo “Ctrl + Shift + E”.
Iniciar sesión o registrarse en la instacia de GitLab en modo Standard con usuario y contraseña.
Modificar el contenido del fichero al que nos ha redirgido y pulsar “Commit changes”. Para modificar el fichero, debemos seguir la sintaxis de Markdown. Existen muchos post en internet donde se explica la sintaxis de Markdown, uno de ellos podría ser este enlace.
Esperar 30 segundos o un minuto a que termine de completarse la integración y despliegue contínuo (CI/CD) y refrescar la página web con “Ctrl + Shift + R” para recargar la página sin utilizar la caché del navegador. Si todo ha ido correctamente, se podrán visualizar los nuevos cambios.
Pasos:
Iniciar sesión o registrarse en la instacia de GitLab en modo Standard con usuario y contraseña. Los enlaces se encuentran en la barra lateral en “Framagit repo”.
Una vez nos encontremos en el repositorio de la página web, pincharemos en Web IDE para abrir un entorno de desarrollo integrado en GitLab. Podremos observar la estructura de directorios de un proyecto creado con Hugo. Si se quiere saber más sobre esta estructura, la mejor opción es ir directamente a la documentación de Hugo sobre la estructura de directorios.
Nos desplazaremos al archivo content/contribute/template-to-edit.es.md y copiaremos el código con la separación entre +++ (incluidas las separaciones).
Una vez copiado, tendremos que decidir dónde crear la nueva entrada y si se trata de un capítulo nuevo o no. A efectos prácticos, un capítulo es una sección en la barra lateral que sirve para estructurar la información de forma anidada. En caso de ser un nuevo capítulo, se requiere crear una nueva carpeta que contenga un archivo _index.md. En vez de copiar la plantilla anterior, podremos copiar cualquier otro archivo _index.md a modo de ejemplo. Una vez tomada la decisión de si es capítulo o no, crear un nuevo fichero con el nombre que se quiera y que termine en .md. También se puede poner la extensión .es.md para que detecte el castellano como el idioma en el que se encuentra escrito el archivo.
Pegamos al inicio del fichero los metadatos de la plantilla modificando lo que sea necesario (título, fecha, peso, …). La fecha tiene que ser una fecha pasada para que se publique, sino querará oculta hasta dicho día. El peso tiene que ser distinto al especificado en los demás archivos del capítulo. Por lo general, se puede sumar 5 o 10 al valor peso de la anterior entrada.
Seguimos añadiendo el contenido que queramos.
Una vez esté terminado (o queramos guardar los cambios para comprobar que todo funciona correctamente), pulsaremos “Create commit” y “Commit to main branch”. Escribimos un breve mensaje con los cambios realizados y pulsamos “Commit”.
Esperar 30 segundos o un minuto a que termine de completarse la integración y despliegue contínuo (CI/CD) y refrescar la página web con “Ctrl + Shift + R” para recargar la página sin utilizar la caché del navegador. Si todo ha ido correctamente, se podrán visualizar los nuevos cambios.
Para seguir estos pasos se requiere conocimientos básicos del lenguaje de marcado Markdown y una cuenta en la instancia de GitLab donde se aloja la página web. Además, se requieren conocimientos básicos de git, aunque si no los tienes, este puede ser un buen momento para aprender a utilizar este sistema de gestión de versiones.
Pasos:
ssh-add, sólo será necesario introducir una vez la contraseña SSH y la autenticación es más fuerte al hacerse por claves público-privadas.# SSH
git clone git@framagit.org:hacklab/hacklab.frama.io.git
# HTTPS
https://framagit.org/hacklab/hacklab.frama.io.git
git submodule update --init
Si estás en Debian o Ubuntu, se recomienda instalar una versión > 0.104.1. Puedes seleccionar el fichero hugo_extended_XXX_linux-XXX.deb desde releases. Una vez descargado dirígete a la carpeta de Descargas y corre:
Es muy importante que se instale la versión extended, sino el tema elegido no funcionará.
```bash
sudo dpkg -i nombredelpaquete.deb
```
Para comprobar que la versión instalada es la correcta corre:
```bash
hugo version
```
Si usas Mac asumiendo que tienes [Homebrew](https://brew.sh/):
```bash
brew install hugo
```
Si estás con Windows y usas [Chocolatey](https://chocolatey.org/):
```
choco install hugo -confirm
```
Servir la web con hugo serve y abrir http://localhost:1313 en el navegador.
Lo ideal es utilizar los issues y merge requests para indicar qué cambio vamos a realizar en el código. Aunque al principio puede parecer un poco lioso, son buenas prácticas para la revisión de código y adminitración de tareas. En caso de abrir un issue con un merge request asociado, utilizarempos git checkout -b feat/nueva-rama para editar sobre ella. Abriremos el proyecto con el editor de código preferido y modificaremos un archivo en la carpeta content/.
Visualizar los cambios en el navegador después de guardar el fichero modificado. Comprobar que los cambios funcionan en local.
Después de comprobar que todo funciona, si hemos creado un merge request asociado al issue que queremos solucionar, haremos un commit en la rama creada con git commit -m "Mensaje descriptivo de los cambios" y subirlo al repositorio origen con git push origin feat/nueva-rama. En este caso, se habrá creado un merge request que habrá que aprobar para que se fusionen los cambios de la feat/nueva-rama con la main. Si no hemos creado un merge request asociado, simplemente haremos un commit en la rama main y lo suberemos al repositorio de origen.
Esperar 30 segundos o un minuto a que termine de completarse la integración y despliegue contínuo (CI/CD) y refrescar la página web con “Ctrl + Shift + R” para recargar la página sin utilizar la caché del navegador. Si todo ha ido correctamente, se podrán visualizar los nuevos cambios.
Previamente, es necesario completar los pasos de la sección anterior hasta el paso 4, incluido.
Pasos:
Abrir el proyecto con el editor de código preferido y con una terminal. Si queremos crear un nuevo capítulo o sección con el nombre nuevo, ejecutamos lo siguiente:
hugo new --kind chapter nuevo/_index.md
Si simplemente queremos crear una nueva entrada, escribimos:
hugo new hugo/quick_start.md
Después, ya se podrá visualizar los cambios en el navegador después de guardar el fichero modificado.
Hacer un commit en la rama main y subirlo a la instancia de GitLab.
Esperar 30 segundos o un minuto a que termine de completarse la integración y despliegue contínuo (CI/CD) y refrescar la página web con “Ctrl + Shift + R” para recargar la página sin utilizar la caché del navegador. Si todo ha ido correctamente, se podrán visualizar los nuevos cambios.
Lo más importante para utilizar esta plantilla es copiar los metadatos de arriba (todo lo escrito entre los dos separadores +++). Lo demás se puede borrar.