En el último artículo del Manual de Hugo estuvimos hablando de los layouts de Hugo y cómo se puede construir un layout base, que se usará a lo largo del sitio. También tuvimos ocasión de aprender otros asuntos interesantes como es el uso de partials.

Todos esos son temas muy importantes, porque necesitarás aplicarlos para componer sitios con diseño y estructura personalizada para tus proyectos. Sin embargo, para hablar de Layouts personalizados tenemos que seguir explicando cosas importantes, como es la existencia de diversos tipos de templates que usa el framework para poder componer páginas de distintos tipos.

En Hugo Framework existen varios tipos de templates y un orden de importancia, mediante el cual el sistema de generación de sitios estáticos es capaz de escoger un template u otro. En este artículo vamos a abordar los dos tipos de templates más importantes, que nos van a servir para la mayoría de los sitios, que son el "single" y el "index" de una colección.

Lookup Order de Hugo

Antes de comenzar a explicar cómo usar estos templates y en qué casos aplica cada uno, vamos a mencionar que es el Lookup Order de Hugo y dónde puedes consultarlo para saber cuál será el template que se aplicará en cada tipo de contenido.

El "Lookup Order" de Hugo indica qué plantilla de entre todas las posibles va a escoger el sistema de generación del sitio, en función del contenido que tenga que generar.

Existen unas reglas bastante complejas que permiten al framework ser muy detallista sobre la plantilla que va a usar para renderizar un contenido. Dependiendo del tipo de página, buscará primero unos templates y luego otros, yendo siempre del template más específico hasta el más general. Es decir, si hay un template específico para una página en concreto, lo escogerá antes que el template general, definido para todo el sitio.

Puedes encontrar la información completa de este asunto en la documentación: https://gohugo.io/templates/lookup-order/. Tampoco te tienes que preocupar por saberlo de memoria, ni mucho menos. Es más bien una documentación que debes saber que existe, por si tienes alguna duda sobre cuál es el template que deberías construir para personalizar una parte de tu sitio.

Nosotros en este artículo vamos a mostrar los dos tipos de templates que necesitarás en todo sitio web, lo que nos dará para comenzar bastantes posibilidades para personalización de los sitios. Conocer estos tipos de layouts te ofrecerá la base para construir diseños de Hugo totalmente personalizados. Además, este mismo conocimiento te vendrá bien para aplicarlo cuando trabajes con un tema de terceros (un theme de hugo que hayas aplicado en tu web) y te permitirá entender qué archivos debes sobreescribir para personalizarlo.

Los Layouts más importantes en los sitios de Hugo

En Hugo tenemos dos tipos de layouts que debes conocer, básicamente porque casi todas las páginas los van a tener que usar:

• Single: Este layout sirve para definir el formato de una página de un sitio. El single se aplica en una página suelta, como la típica página de contacto de un sitio, pero también se puede aplicar en una página del post de un blog.
• List: Este layout sirve para definir el formato de una página de portada de una colección. Por ejemplo la portada de una supuesta sección de blog. Dentro de un sitio web puedes tener secciones que incluyan dentro un conjunto de páginas, por ejemplo la sección de blog, productos, casos de éxito o cualquier otra sección similar. Secciones que contienen dentro un conjunto de páginas se llaman colecciones en Hugo y la portada de la colección mostrará básicamente un listado de páginas, las que se incluyen en esa sección, con enlaces a cada una de ellas.

Estos layouts se pueden definir de manera general. Entonces podrás tener un single que aplicará a todas las páginas del sitio y un list que aplicará a todas las portadas de las colecciones. Pero por supuesto, podrías tener un single que aplicase solamente sobre una página en particular, como la de contacto, o un post particular del blog. O un layout list, que aplique sobre todo el sitio o un layout list creado para que aplique solamente sobre una colección en particular. Por tanto, podemos tener en un sitio de Hugo en realidad varios layouts single y varios layouts list.

Cómo definir los layouts Single y List

Al desarrollar un sitio de Hugo tenemos una carpeta "layouts" que es donde vamos a colocar los archivos que hacen de plantilla para las páginas que se van a generar.

Esta carpeta ya la comenzamos a usar en el artículo anterior. Vimos en ese artículo cómo crear el layout "baseof.html", que nos sirve como plantilla de base para todo el sitio y por tanto contendrá como el marco común a todas las páginas, con su cabecera, pie, etc.

Dentro de la carpeta "layouts/_default" ya colocamos el "baseof.html" pero también vamos a colocar ahora los layouts base "single.html" y "list.html", que serán los principales templates predeterminados para ese tipo de contenido que acabamos de describir.

Para definir esos layouts vamos a comenzar por crear dichos archivos, creando esta estructura de ficheros y carpetas en el sitio.

Layout single.html de Hugo

Antes de ver cómo sería un layout "single.html", tenemos que recordar que estos layouts no van a comenzar desde cero, sino que tendremos una base general en el sitio, que nos aporta el archivo "baseof.html".

Tal como explicamos, en el "baseof.html" teníamos bloques, que se habrán de rellenar más adelante con contenido.

{{ block "main" . }}
  <p>Este es el bloque main definido en "baseof.html"</p>
{{ end }}

Ahora que tenemos esto en mente, vamos a explicar cómo vamos a realizar el template "single.html", de modo que se reutilice "baseof.html" y se completen los bloques que este layout tenga definidos.

Este será el contenido del single.html, que como ves solamente necesita definir el bloque "main" que había dentro del baseof.

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  <div>
    {{ .Content }}
  </div>
{{ end }}

Dentro de este single encontramos:

• La estructura define nos sirve para definir el contenido que irá dentro de un bloque.
• La expresión {{ .Title }} sirve para colocar el título de la página que se está renderizando mediante este layout.
• La expresión {{ .Content }} sirve para colocar el contenido de la página que se está renderizando.

Crear un contenido donde se aplicará el single.html

Ahora, para ver cómo se aplicará ese layout puedes crear un archivo de contenido para la página de contacto, por ejemplo. Lo hacemos con el CLI de Hugo con el comando:

hugo new contactar.md

Esa página se generará en la carpeta "content" y tendrá un contenido básico, que vamos a modificar para que se quede más o menos así.

---
title: "Contactar"
date: 2021-09-27T17:30:33+02:00
---

Hola esta es la página de contacto

Muchas gracias...

Como puedes ver, esta página está compuesta como de dos partes. Por un lado tenemos lo que se llama el Front Matter de Hugo, que es el bloque inicial que está separado por "---". Ese bloque define una metainformación de la página y es esencial en la construcción de sitios de Hugo.

Por otro lado tenemos el contenido, que es básicamente todo el markdown que está debajo del Front Matter. Ese contenido puede ser tan extenso como se desee.

Pues bien:

• Lo que se coloca en el template "single.html" como {{ .Title }} es la propiedad "title" que ves en el Front Matter
• Lo que se coloca en el sigle como {{ .Content }} es para que aparezca ahí todo el contenido que se haya definido en el archivo de markdown.

Puedes poner en marcha el sitio y comprobar cómo se ve la página de contacto gracias a este nuevo layout single.

Layout list.html de Hugo

Ahora vamos a ver el otro layout que nos ocupa en este artículo, el "list.html". Básicamente lo que haremos será definir de nuevo el bloque "main", creando tambien el marcado para mostrar el {{ .Title }} y el {{ .Content }} que ya conocemos.

Pero en esta ocasión además vamos a usar otra construcción interesante que nos va a permitir aprender a crear bucles o repeticiones en los layouts de Hugo. Lo haremos con la estructura "range".

Este es código del layout "list.html".

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  <div>
    {{ .Content }}
  </div>
  {{ range .Pages }}
    <p>
      <a href="{{ .URL }}">{{ .Title }}</a>
    </p>
  {{ end }}
{{ end }}

Lo nuevo aquí es la estructura "range" que sirve para hacer una repetición. En este caso está iterando por la propiedad .Pages.

Para entender .Pages debemos pensar que este template es para una portada de una colección. Por tanto, .Pages será la propia colección de páginas que tenga la sección donde se use el template list.html.

Prestemos atención al bloque range para entender su funcionamiento.

{{ range .Pages }}
    <p>
      <a href="{{ .URL }}">{{ .Title }}</a>
    </p>
{{ end }}

Como hemos dicho, lo que hará será recorrer la colección .Pages y por tanto colocará un párrafo para cada una de las .Pages de esta colección.

Lo importante es que dentro del cuerpo del range, lo que tenemos es cada una de las páginas, por lo que, cuando nos encontramos {{ .Title }} no va a hacer referencia al título de la página portada de la colección, sino al título de la página actual en la iteración del range.

Además, de igual manera, cuando vemos {{ .URL }} no hace referencia a la URL de la página portada de la colección, sino a la dirección de la página de la iteración actual del range.

Crear un contenido donde se aplicará el list.html

Para poder ver cómo se aplica este layout tenemos que crear una colección de elementos. En realidad necesitaremos la portada de la colección y varias págnas dentro de esa colección.

Para ello vamos a lanzar los comandos:

hugo new blog/_index.md

Ese comando creará la portada del blog.

Luego necesitaremos algunas páginas en el blog, que podemos crear con los comandos:

hugo new blog/post1.md
hugo new blog/post2.md

La página que usará el template "list.html" es la portada del blog, a la que podremos acceder con esta dirección:

http://localhost:1313/blog

Puedes encontrar el bloque donde aparecen los enlaces en la siguiente imagen:

Conclusión

Hemos visto un par de ejemplos sencillos de templates para aplicar en un sitio web desarrollado con Hugo. Los layouts cubren los tipos de contenido más importantes: el single y el list.

Los layouts que hemos construido son muy básicos y no tienen absolutamente ningún diseño, pero lo que importa, y esperamos que haya quedado claro, es cómo esas distintas plantillas se aplicarán dependiendo del tipo de contenido que se debe generar. A partir de aquí ya es aplicarle un marcado más elaborado, con los bloques que necesites en tu sitio web.

Para acabar te dejamos con un vídeo en el que podrás ver todo el proceso de creación de los layouts Single y List que hemos explicado en este artículo. Esperamos que te guste!