Cómo publicar una entrada en este blog

Este blog es un sitio estático generado con Hugo y desplegado en GitLab Pages. Cada entrada es un fichero Markdown dentro de su propia carpeta, y publicar consiste en fusionar ese fichero en la rama main. En Gaia Lab hemos recogido aquí los pasos completos para que cualquier miembro del equipo pueda escribir y publicar sin depender de nadie.

Crear la entrada #

Clona el repositorio y crea la entrada con hugo new content. Hugo aplica el arquetipo archetypes/posts.md a todo lo que cuelga de posts/, de modo que el fichero nace con el front matter ya preparado y con draft: true.

git clone <url-del-repositorio> gaia-blog
cd gaia-blog
hugo new content posts/mi-entrada/index.md

El resultado es una carpeta content/posts/mi-entrada/ con un index.md dentro. Hugo llama a esto un page bundle: las fotos y vídeos de la entrada se copian a esa misma carpeta y se referencian por su nombre, sin rutas. El nombre de la carpeta es la URL final de la entrada, así que conviene que sea corto, en minúsculas y sin acentos.

El front matter #

El bloque YAML entre los dos --- describe la entrada. Todas las claves deben estar presentes aunque queden vacías.

Esta misma entrada se ha publicado sin portada a propósito, para comprobar cómo se ve una tarjeta sin imagen.

Markdown útil #

El cuerpo se escribe en Markdown estándar. Lo que más usamos:

## Encabezado de sección
### Subsección

- Elemento de lista
- Otro elemento

| Parámetro | Valor |
|---|---|
| Red | 5G SA |

> Cita o resultado destacado.

```python
print("código con resaltado por lenguaje")
```

![Texto alternativo descriptivo](foto.jpg "Pie de foto")

La imagen va en su propio párrafo y el texto entre comillas se convierte en el pie de foto. Así queda una foto real copiada a la carpeta de esta entrada:

Además del Markdown, la plantilla ofrece tres shortcodes de Hugo:

{{< note title="Nota" >}}
Aviso lateral. Admite Markdown y `type="warning"`.
{{< /note >}}

{{< video src="clip.mp4" poster="clip.jpg" caption="Pie del vídeo" >}}

{{< youtube ID_DEL_VIDEO >}}

Y así se ve el primero de ellos en uso:

Ver la web en local #

hugo server -D

El sitio queda en http://localhost:1313/. Como la baseURL de hugo.toml lleva ruta (/blog/), Hugo la conserva en local y la dirección real es http://localhost:1313/blog/. La opción -D muestra también los borradores; sin ella, y en el despliegue, una entrada con draft: true no existe. Los cambios en el Markdown se recargan solos en el navegador.

Publicar #

Publicamos siempre desde una rama y a través de un merge request:

git checkout -b post/mi-entrada
git add content/posts/mi-entrada/
git commit -m "Entrada: mi entrada"
git push -u origin post/mi-entrada

Al abrir el merge request en GitLab, el pipeline ejecuta el job build, que comprueba que el sitio compila y guarda el resultado como artefacto. Cuando el merge request se fusiona en main, el job pages vuelve a construir el sitio con la URL definitiva y lo despliega en GitLab Pages; la entrada aparece en uno o dos minutos.

Fotos y vídeos #

Las fotos se suben en JPG de entre 1400 y 2000 px de ancho, orientadas y sin metadatos. Con ImageMagick:

magick foto.JPG -auto-orient -strip -resize 1600x -quality 80 salida.jpg

Los vídeos van en MP4 H.264 con el índice al principio del fichero (faststart), para que empiecen a reproducirse antes de descargarse enteros. El primer comando recodifica cualquier vídeo a H.264; el segundo vale cuando ya es H.264 y solo hay que mover el índice, sin recodificar:

ffmpeg -i original.mp4 -c:v libx264 -crf 28 -movflags +faststart clip.mp4
ffmpeg -i clip.mp4 -c copy -movflags +faststart salida.mp4

No subas al repositorio originales pesados, ni RAW, ni vídeos completos: el material sin procesar se guarda fuera del repositorio y a la carpeta de la entrada solo llega la versión optimizada.