Temas y plantillas en Hugo – Parte 4

En esta serie de artículos sobre el gestor de contenidos Hugo, vamos a centrarnos en los temas.

En el siguiente enlace podemos ver cientos de ejemplos de temas para Hugo:

http://themes.gohugo.io/

Para instalarlos sólo hay que descargarlos y copiarlos en la carpeta themes de nuestro sitio. Aunque la mayoría de los temas los podemos instalar usando el comando git.

Algunos temas nos van a requerir alguna distribución especial de los contenidos o introducir alguna configuración especial en el sitio. Esto lo podemos ver en las descripciones de los temas.

Los temas se crean a través de las plantillas (Templates) de Hugo. Básicamente una plantilla es un fichero html y en el que vamos a encontrar algunas etiquetas especiales del tipo “{{ algo }}”.

Por ejemplo:

<!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
</head>
<body>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</body>
</html>

Esto es una plantilla html del lenguaje Go. Para ver una introducción a este lenguaje podemos consultar la documentación de Hugo sobre las plantillas:

https://gohugo.io/templates/go-templates/

En el ejemplo anterior, se puede ver que aparece la etiqueta “{{ .Title }}”, que lógicamente se reemplaza por el título cuando el sitio se construye. También tenemos la etiqueta “{{ .Content }}”, que se reemplazará por el contenido.

Temas y layouts

Hay dos carpetas que nos var interesar la carpeta themes y la carpeta layouts. Generalmente layouts estará vacía y cuando se tenga que crear un sitio, se tomarán los archivos de themes y se usará el tema que se haya seleccionado. Puede ocurrir que deseemos que independientemente del tema a utilizar, se use una determinada configuración para la página de inicio (por ejemplo), podemos entonces crear nuestra página de inicio en layouts que se usará independientemente del tema que se vaya a poner por defecto.

Plantillas principales de Hugo

Tenemos la plantillas:

  • Single: Representa cómo se va a dibujar una entrada o un elemento simple de contenidos
  • List: Representa cómo se va a dibujar una lista de contenidos.
  • Homepage: Es la página de inicio de nuestro sitio.

Empecemos por la página de inicio, la vamos a entrar en el directorio “themes/nuestro-tema/index.html”. Probad a editarla y veréis cómo se modifica la página de inicio de vuestro sitio.

Según el tema, también deberéis tocar ciertos parámetros de la configuración para cambiar ciertos elementos del tema.

Pero antes de continuar vamos a ver las posibilidades de las plantillas de Go.

Plantillas de Go

Variables

Hugo usa las plantillas del lenguaje Go para procesar el texto html de forma muy rápida. Como ya se ha dicho, las plantillas van entre los símbolos {{ }}. Así, por ejemplo, para obtener el valor de una variable ya definida se pondría:

<!DOCTYPE html>
<html>
<body>
  {{ variable }}
</body>
</html>

Las variables que define Hugo, se pueden encontrar en:

http://gohugo.io/templates/variables/

Para definir el valor de una variable también se puede usar el símbolo $ delante de la variable:

{{ $variable := "Hola mundo" }}

Después se obtiene su valor:

{{ $variable }}

Hugo también permite usar funciones, las funciones predefinidas se pueden encontrar en:

http://gohugo.io/templates/functions/

Para usar una función simplemente se la llama por su nombre:

{{ función }}

Para pasar argumentos a una función, se ponen los argumentos separados por espacios:

{{ add 1 2}}

La función add suma dos valores, en este caso devolverá 3.

Iteraciones

Las plantillas de Hugo permiten iterar entre los elementos de una array. Para ello se usará “range”. Por ejemplo, para listar todos los elementos de un array:

{{ range $elemento := array }}
    {{ $elemento }}
{{ end }}

Vamos a verlo funcionar, se abre el archivo index.html, dentro de nuestra carpeta themes/tema, e introducimos:

{{ range $pagina := .Data.Pages }}
    Títulos de páginas: {{ $pagina.Title }}<br/>
{{ end }}

Ahora al generar el sitio veremos el contenido que se ha introducido al ejecutar “range”.

Se puede también acceder por contexto:

{{ range array }}
    {{ . }}
{{ end }}

En el ejemplo que estábamos manejando:

{{ range .Data.Pages }}
    Títulos de páginas: {{ .Title }}<br/>
{{ end }}

Por último, se pueden usar mapas, para iterar en el mapa se puede usar la siguiente construcción:

{{range $índice, $elemento := array}}
    {{ $índice }}
    {{ $elemento }}
{{ end }}

En nuestro ejemplo:

{{ range $index, $page := .Paginator.Pages }}
    {{ $index }}
    {{ $page.Title }} <br/>
{{ end }}

Condicionales

La estructura if está soportada por la plantillas de Go. Por ejemplo:

{{ if lt 2 3 }}
    Cierto
{{ end }}

que significa si 2 es menor que 3 escribe “Cierto”.

Disponemos de los comparadores:

  • eq Devuelve verdadero si arg1 == arg2
  • ne Devuelve verdadero si arg1 != arg2
  • lt Devuelve verdadero si arg1 < arg2
  • le Devuelve verdadero si arg1 <= arg2
  • gt Devuelve verdadero si arg1 > arg2
  • ge Devuelve verdadero si arg1 >= arg2

Se puede usar and y or para añadir nuevas condiciones, pero hay que tener en cuenta que en la plantillas de Go los argumentos van siempre detrás de la función:

{{ if and (lt 2 3) (gt 3 2) }}
    Cierto
{{ end }}

Por supuesto, la estructura if-else también se puede usar:

{{ if lt 3 2 }}
    False
{{ else }}
    Cierto
{{ end }}

Else if:

{{ if lt 3 2 }}
    False
{{ else if gt 3 2 }}
    Cierto
{{ end }}

Se puede usar not para negar una condición:

{{ if not lt 3 2 }}
    Cierto
{{ end }}

Contextos

A veces tenemos que hacer referencia a objetos dentro de otros objetos y hay que escribir mucho código. Una forma de hacer esta tarea más cómoda es usando with. En el siguiente ejemplo, cada vez que nos refiramos a . dentro de la estructura with, nos estaremos refiriendo a “.Params.title”:

{{ with .Params.title }}
    <h4>{{ . }}>
{{ end }}

Tuberías

Se tiene algo similar a las tuberías UNIX, por ejemplo, supongamos la siguiente operación matemática:

{{ add 5 (add 3 2) }}

Se podría escribir de la siguiente forma:

{{ add 3 2 | add 5 }}

Como se puede ver el resultado de la suma 3+2 se pasa como último argumento de la siguiente operación “add 5”.

Se pueden encadenar varias tubería:

{{ add 3 2 | add 5 | add 4}}

Uso del operador . en contextos

El operador {{ . }} siempre se refiere al contexto actual. Nos sirve para llamar a variables y a varibles dentro de variables (“.Params.title”). Dentro de un bucle {{ . }} se referirá al valor del elemento actual. Si es necesario acceder al contexto global, se puede usar $., por ejemplo:

{{ range .Data.Pages }}
    Títulos de páginas: {{ .Title }}
    {{ $.Site.Title }} <br/>
{{ end }}

Includes

Se puede incluir un archivo dentro de otro. Por ejemplo, podríamos tener en una archivo la cabecera que queremos que aparezca en todas las páginas web de nuestro sitio. En otro archivo el pie de página. En cada página que escribamos, podemos incluirlos usando:

{{ partial "cabecera" . }}

Texto de la página

{{ partial "pie" . }}

De forma automática Hugo incluirá el pie y la cabecera en la página. Si hacemos una modificación en la cabecera, todas las páginas en las que hayamos incluido la cabecera, recibirán la actualización.

Para incluir archivos podemos usar el comando partial:

{{ partial "archivo" contexto }}

El archivo debe estar localizado en el directorio layout/partials. El contexto se refiere a las variables a las que tendrá acceso el archivo incluido, normalmente acceden a “.”.

Tenemos otra forma de incluir archivos usando template:

{{ template "archivo" contexto }}

La diferencia se encuentra en que el archivo a incluir deberá estar en layout. La documentación de Hugo recomienda usar partial.

Si exploráis los temas de Hugo vais a ver buenos ejemplos del uso de partial.

Existe otra forma de incluir plantillas, la función “.Render”. Para introducir contenidos con “.Render” sólo hay que incluir el nombre de la plantilla a utilizar. Por ejemplo, para ver la plantilla “summary.html”:

{{ .Render "summary"}}

Eliminando espacios en blanco

Imaginad que el comando “.Title” devuelva un título con espacios en blanco y saltos de línea antes y después, por ejemplo:

<h1>{{ .Title }}</h1>

e imaginad que la salida final fuera:

<h1>
    Ejemplo de título
        </h1>

Esta salida no es elegante ni cómoda de leer a la hora de editar código.

Usando el operador {{- -}} se pueden eleminar estos espacios:

<h1>{{- .Title -}}</h1>

La salida final sería:

<h1>Ejemplo de título</h1>

Paso de parámetros a las pantillas

Hugo tiene predefinidas una serie de variables que pueden ser útiles:

http://gohugo.io/templates/variables/

A través de los archivos de configuración o a través de metadatos, se pueden pasar parámetros, definidos por el usuario, a las plantillas. Supongamos que se define la sección params en el archivo “config.toml”. Dentro de esta sección definimos las variables que necesitamos, por ejemplo:

baseurl = "http://localhost:1313"
languageCode = "es"
title = "Ejemplo de nuevo sitio"

[params]
ejemplo = "Ejemplo de valor definido"

Dentro de uno de los archivos del tema podremos introducir:

{{ .Site.Params.Ejemplo }}

y allí obtendremos el valor de la variable.

De forma similar se pueden definir variables en la cabecera de las entradas. Por ejemplo, si se tiene la entrada “hola-mundo.md”, se podría introducir la variable “Fecha”:

+++
date = "2017-04-07T01:04:36+02:00"
title = "hola mundo"
Fecha = true

+++

Hola mundo **esto** es un ejemplo.

Ahora se podría ir a la parte del tema correspondiente y hacer que si Fecha es true, se muestre la fecha de esta entrada:

{{ if .Params.Fecha }}
    {{ .Date.Format .Site.Data.Formats.date }}
{{ end }}

Como se puede ver usando “.Params.parámetro” se puede acceder al valor de la variable.

Para terminar

Hasta aquí esta breve introducción a los temas Hugo. Un par de recomendaciones:

La primera, ver la documentación oficial de Hugo:

https://gohugo.io/templates/go-templates/

Por otro lado es bueno bajarse un tema y explorarlo y modificarlo. Veremos que se usan cosas como “.Render” que llama a alguna plantilla para mostrar los contenidos. Para no volvernos locos buscando los archivos se recomenda usar los comandos de UNIX grep y find:

Con grep buscaremos los archivos que contengan algún tipo de texto que nos interese:

grep -Re 'texto a buscar'

Por otro lado find nos ayuda a buscar archivos por su nombre:

find . -name "nombre del archivo"

En el nombre del archivo se pueden introducir wildchars como son el * y la ? que nos ayudan a buscar los archivos de forma más cómoda.

Anuncios
Esta entrada fue publicada en Software y etiquetada . Guarda el enlace permanente.

4 respuestas a Temas y plantillas en Hugo – Parte 4

  1. Pingback: Temas y plantillas en Hugo – Parte 4 | PlanetaLibre

  2. nasciiboy dijo:

    gran tutorial de hugo, sobre todo el enigmatico asunto de las plantillas, que para entenderlo a profundidad es necesario conocer su prosedencia como libreria de golang, en particular comprender de donde demonios surgen esos “valores magicos”

    en english, no entendia bien eso del significado del punto, gracias por aclararme el tema

    dos dudas: primero, cuando se evalua la plantilla las condicinose/rangos/cosas dejan lineas en blanco en el resultado, pero con los “-” el resultado quedaria siempre “pegado” a la primer cosa previa, creo que es un defecto de la libreria de templates, se puede corregir?

    segundo: al generar el sitio, como hacer para que un post tenga su propia carpeta, es decir, si tengo “content/categoria/carpeta-post/post.md” no se exporta como “public/categoria/carpeta-post/index.hmtl”, sino como “public/categoria/carpeta-post/carpeta-post/index.hmtl”. Ademas no se si es error mio, o la forma en que funciona hugo, pero para hacer referencia a imigenes y contenido de la direccion donde esta el post siempre tengo que anteceder la ruta con “..” (dos puntos), por ejemplo en lugar de colocar “[](imagen.jpg)” hay que hacer “[](../imagen.jpg)”, es un error de diseño?

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s