> Manuales > Manual de Hugo

En este artículo aprenderás a cambiar el diseño un sitio web realizado con Hugo, el generador de sitios estáticos, y personalizar un tema para adaptarlo a tus necesidades, alterando HTML, CSS, imágenes, iconos...

Personalizar un tema de Hugo

Hugo es un fantástico generador de sitios estáticos que permite crear rápidamente sitios web, con contenido personalizado. Una vez producido el sitio se genera en archivos planos de HTML, CSS y Javascript, lo que impacta muy positivamente en la velocidad del sitio y la seguridad.

En el pasado artículo nos dedicamos a dar los primeros pasos con Hugo y pudimos aprender muchas de sus principales características y el flujo de desarrollo y publicación de la página web. Creamos contenido personalizado y pudimos aprender la diferencia entre páginas y colecciones, personalizar los menús y mucho más. Para la realización de los pasos de este tutorial partiremos de donde lo dejamos en el pasado artículo.

Para que nuestro trabajo fuera más sencillo nos basamos en un tema ya realizado, que instalamos en nuestro proyecto. Esto nos permitió conseguir resultados adecuados con muy poco esfuerzo. Sin embargo, cuando llega la hora de la verdad, no siempre lo que nos ofrece el tema nos sirve tal cual, sino que tendremos que personalizar el diseño. Es decir, agregar el logotipo de la empresa, manipular la portada, cambiar el CSS, header, footer, iconos... Todo eso es lo que vamos a explorar en este artículo.

Directorio static

En el directorio "static" de nuestro proyecto Hugo podemos agregar todo tipo de archivos que se van a servir tal cual, sin ningún tipo de procesamiento.

Es un buen lugar para colocar todo tipo de contenidos extra, que queremos que se agreguen en nuestro sitio web, como imágenes o librerías.

Vamos a comenzar usando esta carpeta para colocar una imagen que podrá ser el logotipo de la empresa para la que estamos construyendo el sitio web.

Básicamente, todo lo que pongamos en la carpeta static se mapeará como si estuviera colgando de la raíz de nuestro sitio web.

Por ejemplo, supongamos que tenemos dentro de static un recurso que es una imagen "logo.png" y la tenemos en la carpeta "static/images".

Nota: Recuerda que la URL donde se va a publicar el sitio web la puedes configurar en el archivo "config.toml". Esa URL se indica en la variable "baseURL" y podría ser un dominio tal cual, example.com o una carpeta dentro de ese dominio example.com/mi-sitio. En el caso del artículo anterior, que finalizamos con una publicación en Github Pages, la URL final no era un dominio a secas, sino un nombre de dominio y luego un directorio. Esto es perfectamente parametrizable.

Personalizar el layout del tema

Ahora que ya tenemos un logotipo de la empresa, la imagen colocada en static/images/logo.png, lo querrás situar en el layout del sitio web, en la parte de la cabecera. Para conseguirlo vamos a tener que modificar el HTML del layout del tema.

Para nuestro sitio web hemos instalado un tema de terceros, que ya tiene sus propios layouts. No es buena muy buena idea modificar directamente los archivos del tema, que hemos instalado en la carpeta de "themes". Es mucho mejor dejar esos archivos inalterados y crear nuestras propias plantillas, sobreescribiendo las existentes. De este modo mantenemos separado nuestro propio código del código heredado del tema de turno.

Cuando Hugo tiene que renderizar una página lo hace en base a los layouts del tema. Los podemos encontrar en la carpeta del tema. Por ejemplo en nuestro caso los tenemos dentro de "themes/tale/layouts", ya que el tema que habíamos instalado se llama "tale". Estos layouts son los que usará Hugo, a no ser que nosotros decidamos sobreescribirlos.

Cada vez que Hugo va a utilizar un layout primero comprueba que no haya una versión local de ese layout en nuestro proyecto. Estas versiones locales, creadas por nosotros, las podemos colocar en la carpeta "layouts", respetando la misma estructura de archivos y carpetas que el tema haya definido.

En nuestro caso queremos sobreescribir el layout que monta la cabecera de la página. Esta operación la podemos realizar de la siguiente manera.

El layout original del tema está en:

/themes/tale/layouts/partials/header.html

Para sobreescribirlo crearemos un archivo en la ruta siguiente de nuestro proyecto:

/layouts/partials/header.html

En ese archivo colocaremos el código tal cual queremos que se muestre la cabecera de las páginas. Como Hugo detectará que en la carpeta "layouts" de nuestro proyecto hay una sobreescritura del template "header.html" la usará en lugar de la predeterminada por el tema instalado.

Simplemente se trata de copiar el template original del tema y alterar las partes que sean necesarias. Es todo!

El tema original tenía este código:

<nav class="nav">
  <div class="nav-container">
    <a href="{{ "/" | relURL }}">
      <h2 class="nav-title">{{ .Site.Title }}</h2>
    </a>
    {{ partial "header-menu.html" . }}
  </div>
</nav>

Nosotros queremos colocar una imagen en vez de un heading h2, por lo tanto podríamos usar este otro código para este template header.html.

<nav class="nav">
  <div class="nav-container">
    <a href="{{ "/" | relURL }}">
      <img src="{{ .Site.BaseURL }}images/logo.png" alt="InmoCasas">
    </a>
    {{ partial "header-menu.html" . }}
  </div>
</nav>

Lo hemos alterado lo mínimo posible para conseguir nuestro objetivo. Sin embargo, veremos algo interesante que nos viene bien para aprender cosas nuevas de Hugo, la variable .Site.BaseURL.

Variables de Hugo e interpolación en templates

Existen muchas variables dentro de Hugo que podemos usar para distintos objetivos. En este caso vamos a usar una global que nos permitirá asegurar que las imágenes se enlazan correctamente con los archivos que tenemos en la carpeta static.

Dado que la URL de publicación del sitio web es variable (podría estar localizada en la raíz del dominio o en una carpeta interna) tenemos que usar la variable .Site.BaseURL para asegurarnos que la ruta de la imagen se creará correctamente. Esta variable contiene la ruta base de nuestra URL definida en el archivo de configuración config.toml.

baseURL = "https://example.com/mi-sitio/"

Para usar una variable dentro de un template tenemos que realizar su interpolación, usando la sintaxis de las dos llaves.

{{ variable }}

Esto simplemente vuelca el contenido de la variable en el código HTML del sitio generado.

La variable que nos ocupa al volcarse en el template se mostrará tal cual lo hemos configurado en el archivo, por lo tanto la imagen que hemos colocado con este código:

<img src="{{ .Site.BaseURL }}images/logo.png" alt="InmoCasas">

Renderizará como:

<img src="https://example.com/mi-sitio/images/logo.png" alt="InmoCasas">

Y, si estamos en la etapa de desarrollo en local, la URL sería algo como: (el servidor de desarrollo se encargará de realizar esa transformación)

<img src="http://localhost:1313/mi-sitio/images/logo.png" alt="InmoCasas">

Solo para que nos sirva de referencia, esta misma utilidad para construir la URL de nuestra imagen de manera relativa la podríamos conseguir también mediante este código que usa la función relURL incorporada en Hugo.

<img src="{{ "/images/logo.png" | relURL }}" alt="InmoCasas">

Añadir CSS personalizado al sitio

De la misma manera que no modificamos directamente los layouts del sitio en el propio theme, tampoco es recomendable editar el CSS que ellos proporcionan. En lugar de eso es mucho más cómodo crear nuestro propio archivo de CSS en el proyecto local.

Esto es muy sencillo gracias a que CSS funciona como una cascada y los estilos definidos por último modificarán los definidos al principio.

La mayoría de los temas tienen un código que permite colocar cualquier número de archivos CSS a cargar después de las declaraciones del propio tema. Esto se consigue gracias a un poco de código CSS que encontrarás en el template del header de tu tema de turno.

En nuestro caso el template al que nos referimos está en "/themes/tale/layouts/partials/head.html" y el código que permite agregar nuevas hojas de estilo tiene una forma como esta:

{{ range .Site.Params.css -}}
  <link rel="stylesheet" href="{{ . | relURL }}">
{{ end -}}

Esto es una iteración para colocar una serie de archivos de estilo definidos en una variable llamada .Site.Params.css. Esa variable la tenemos que rellenar con un array dentro del archivo de configuración config.toml.

[params]
  css = ["css/estilos.css"]

Como te imaginarás, puedes colcar cualquier número de hojas de estilo, en el orden en el que deseas que se vayan escribiendo en la página.

Nota: si tu tema no tuviera disponible esta configuración para agregar otros archivos CSS, simplemente podrías sobreescribir el template "/themes/tale/layouts/partials/head.html" en tu carpeta de layouts local, tal como hemos aprendido a hacer con el template del header.html anteriormente, colocando este código:
<link rel="stylesheet" href="{{ .Site.BaseURL }}css/estilos.css">

Ahora simplemente vamos a crear el archivo de los estilos CSS, que colocaremos en la carpeta "static", en la ruta marcada en la configuración que hemos indicado en el config.toml, en nuestro caso "/static/css/estilos.css".

El código nuestro de personalización del CSS podría ser algo como esto:

body {
  background-color: #f5f5f5;
}
.nav-container img {
  height: 40px;
}
.post-title, .catalogue-title {
  color: #283d7e;
}
.nav a {
  color: #0768ce;
}

Cambiar los iconos del sitio web

Ya que estamos personalizando los elementos del head, en el template "/themes/tale/layouts/partials/head.html" habrás podido observar que se enlazan con diversos iconos del sitio web.

Estos iconos también los podemos generar y colocar en la carpeta "static", siguiendo las rutas que se nos marcan.

<!-- Favicon -->
<link rel="icon" type="image/png" sizes="32x32" href="{{ "images/favicon-32x32.png" | relURL }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ "images/favicon-16x16.png" | relURL }}">
<link rel="apple-touch-icon" sizes="180x180" href="{{ "images/apple-touch-icon.png" | relURL }}">

Dado el anterior código, los tres archivos que tendríamos que crear son:

/static/images/favicon-32x32.png
/static/images/favicon-16x16.png
/static/images/apple-touch-icon.png

Tampoco está de más que coloquemos el archivo "favicon.ico" dentro de la raíz de static, ya que algunos navegadores lo irán a buscar allí de manera predeterminada.

/static/favicon.ico

Sobreescribir el template para personalizar el footer

Podemos crear un footer personalizado para nuestro sitio y quitar el que nos aparece en el theme de manera predeterminada.

Tememos esto mismo en el template actual para el footer, en el archivo /themes/tale/layouts/partials/footer.html.

<footer>
  <span>
  &copy; <time datetime="{{ now }}">{{ now.Format "2006" }}</time> {{ .Site.Author.name }}. {{ i18n "generator" | safeHTML }}
  </span>
</footer>

Podríamos personalizarlo simplemente creando una configuración del nombre del autor en el config.toml:

[Author]
  name = "Miguel Angel Alvarez"

Pero también podemos cortar por lo sano y sobreescribir el footer completo, con lo que podríamos agregarle mucho otro código HTML totalmente personalizado, imagenes, listas de enlaces, etc.

El archivo del template lo sobreescibimos igual que hemos hecho anteriormente, creando el nuevo fichero en la ruta "/layouts/partials/footer.html".

Cambiar el index para alterar la home del sitio web

Quizás tampoco nos acabe de convencer completamente la home del sitio web y queramos personalizarla un poco, ya que empezar de entrada con las novedades del sitio puede estar bien para ciertos blog, pero no siempre será lo que deseeemos.

En este template nos lo han dejado muy fácil, ya que han creado un template llamado "introduction.html" en la ruta "/themes/tale/layouts/partials/index/introduction.html" en el que se puede poner cualquier código que aparecerá en la home del sitio.

Como siempre, no vamos a manipular este fichero directamente, sino que lo copiaremos en nuestro directorio de layouts local, colocando el contenido que deseemos.

El archivo que generaremos se quedará en la ruta "/layouts/partials/index/introduction.html" y podrá tener todo el HTML que queramos.

<div class="indexhero">
  <h1>InmoCASAS</h1>
  <p>Un sitio creado con Hugo</p>
</div>

Sin embargo, si este archivo no lo hubiera contemplado nuestro tema, simplemente sería sobrescribir completamente el archivo del index del sitio, que está en la ruta: "/themes/tale/layouts/index.html".

Conclusión

Hemos podido alterar de manera sencilla el diseño del sitio web. Nuestros cambios han sido mínimos en realidad y hemos tenido que editar pocos layouts y generar pocos archivos. Obviamente, las transformaciones que tendrás que realizar dependerán de tus objetivos y necesidades, pero te hemos dado las guías básicas para que puedas personalizar los elementos más importantes, como el CSS, las imágenes y los templates.

Acabamos el artículo de personalización de temas de Hugo con este vídeo, en el que podrás ver cómo realizamos paso por paso todas estas modificaciones a un template previamente instalado.

Miguel Angel Alvarez

Miguel es fundador de DesarrolloWeb.com y la plataforma de formación online Escu...

Manual