Logo LC3

Theming de Hugo

20 de febrero de 2019 | | Blog, Web

Hace tiempo os hablábamos sobre Hugo y os prometíamos una entrada sobre theming de Hugo.

¿Cómo hacemos un tema de Hugo?

Si ya tenemos instalado Hugo en nuestro entorno, desde la propia terminal ejecutamos el comando hugo new theme nombre-del-tema y se nos crean los ficheros básicos.

Si el caso es que no podemos realizar este comando no pasa nada, simplemente creamos una carpeta con el nombre de nuestro tema y dentro metemos lo necesario para que funcione.

Theming de Hugo

¿Cómo configuramos el tema para que aparezca en nuestra web?

En el archivo config.toml de nuestra página de hugo tendremos un apartado de tema con el tema actual de nuestro sitio web. Para poner el nuestro simplemente ponemos theme = "nombre-del-tema" y todo debería de comenzar a funcionar conforme a nuestro tema esté estructurado.

Partes básicas del theming de Hugo

Los archivos básicos que tendrá nuestro tema son:

README.md

Aquí se describe el tema, el autor, el origen… Básicamente por qué se ha originado el tema y qué fin tiene. Si hay algo que explicar del tema se adjunta aquí para próximos usuarios.

theme.toml

Es el archivo básico del tema, en el se definen el nombre, la licencia, una pequeña descripción, etiquetas, la versión así como el nombre del autor. Esta información es básica para poder trabajar con el tema.

config.toml

Este archivo es opcional. Hace que cada tema pueda tener su propio fichero de configuración, con params y menús tanto globales como por idioma, así como outputformats y mediatypes configurables.

Carpetas básicas

Como hablamos en el anterior post sobre Hugo hay algunas carpetas básicas tanto en la configuración básica de la propia página como del tema.

layouts

Esta carpeta es imprescindible en la creación del tema ya que será de donde saquen las plantillas para realizar la renderización del sitio:

En la carpeta de _default estarán los archivos por defecto y en general es la única imprescindible.

Dentro de ella se encuentran los archivos obligatorios de list.html y single.html. Además podemos tener otros archivos como el home.html o baseof.html para hacer la página de la home o el básico para cuando no encuentre la página por defecto.

Además podremos crear otras carpetas para partes como el header o el footer. Para ello creamos la carpeta partials y cada vez que queramos utilizar ese trozo de códico lo invocamos {{ partial 'nombre-del-parcial' . }}. Es importante que incluyamos el punto al final ya que así importará todo lo que se encuentre en el archivo.

Un ejemplo de baseof.html que iría dentro de _defaults en layout sería:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ .Site.Title }}</title>
    <link rel="stylesheet" src="styles.css" />
  </head>
  <body>
      {{ partial "menu" . }}

      {{ Content . }}

      {{ partial "footer" . }}
  </body>
</html>

Como podemos ver todas las llamadas a elementos generados por Hugo se realizan entre pares de llaves {{}}.

Cuando queremos llamar a un elemento del config.toml del sitio utilizamos {{ .Site.Param }} sustituyendo Param por el parámetro que queramos utilizar.

Para llamar al contenido se utiliza {{ Content . }}. Es importante, de nuevo, el . al final ya que sin él no se llamaría todo el contenido (no sabría a qué parte del contenido llamar realmente).

archetypes

Aquí encontraremos los arquetipos de las diferentes secciones que podemos crear. Los arquetipos son las plantillas de las cabeceras de los archivos .md que creamos para las entradas y el contenido en general de nuestra web y suele tener esta forma:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
---

static

En esta carpeta es donde se encuentran los archivos que alimentarán nuestro tema como los ficheros de css, de javascript o el logo. Son archivos estáticos y que no se van a tocar normalmente pero que sí se utilizan al renderizar el tema.

i18n

Aquí se encontrarían los archivos de traducción del tema, los archivos de los diferentes idiomas.

data

Los diversos archivos de datos que se necesiten irían en esta carpeta.

Resumen

En general crear un tema no es complicado, tan solo hay que saber qué tiene cada carpeta y cómo se construye cada archivo. Un árbol que nos deja bien ver cómo se resuelve esto es el siguiente:

L nuestra-web
  L archetypes
  L content
  L node_modules
  L static
  L themes
    L nuestro-tema
      L archetypes
        L default.md
      L layouts
        L _defaults
          L baseof.html
          L home.html
          L list.html
          L single.html
        L partials
          L header.html
          L footer.html
      L README.md
      L theme.toml
  L config.toml
  L README.md

Todo esto se explica más ampliamente en la documentación de creación de temas de Hugo.

Espero que os haya resultado útil. Si tenéis alguna duda no dudéis en preguntar.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *