De snelste manier om een Hugo site te maken is door gebruik te maken van een bestaand template, of thema. Er zijn verschillende websites te vinden met een groot aanbod thema’s. Thema’s zijn er zowel gratis als betaald. Maar, zoals ik eerder al schreef, is het ook erg leuk om zelf je website te ontwerpen en in een eigen template te vatten.
In het begin kost het even tijd om de weg te vinden in het Hugo-template landschap. In deze post beschrijf ik de basisbegrippen rond het maken van een theme in Hugo en hoe je zelf kunt beginnen met het maken van een template. In het laatste geval is het nodig dat je al een site hebt geïnitieerd met Hugo en dat je je enigszins comfortabel voelt met de terminal. Na kort te laten zien hoe je zelf een thema kunt aanmaken, loop ik door de verschillende onderdelen binnen een thema heen. Dit artikel is vooral bedoeld als eerste inkijk in hoe Hugo templates werken, en niet als tutorial. Bekijk vooral ook de documentatie van Hugo zelf voor meer informatie.
Hugo thema aanmaken
Het aanmaken van een template of thema in Hugo is net zo eenvoudig als het initiëren van een nieuwe website. Binnen een site kun je een nieuw thema aanmaken door naar de map te navigeren en het volgende commando uit te voeren:
hugo new theme <THEMANAAM>
Vervolgens voeg je het thema toe aan de config.toml zodat Hugo weet dat dit het thema is dat gebruikt moet worden. Dit gaat het makkelijkst met:
echo "theme = <THEMANAAM>" >> config.toml
Met dit commando wordt in submap themes en nieuwe map aangemaakt met de opgegeven naam, met daarin de basis voor een nieuw template. Voordat de overige onderdelen verder worden besproken, is het goed om even te kijken naar het bestand LICENSE in de submap van het thema. Hierin wordt aangegeven dat het thema onder de MIT-License valt. Dit betekent dat iedereen vrij is om het thema te gebruiken en desgewenst te wijzigen. Mocht je dit niet willen staat het je natuurlijk vrij om dit aan te passen. Vul in ieder geval wel je naam in op de tweede regel.
Standaard onderdelen Hugo thema
Bij het aanmaken van een Hugo thema worden bepaalde bestanden en mappen automatisch gegenereerd. Dit bestaat uit de volgende mappenstructuur:
├── LICENSE
├── archetypes
│ └── default.md
├── layouts
│ ├── 404.html
│ ├── _default
│ │ ├── baseof.html
│ │ ├── list.html
│ │ └── single.html
│ ├── index.html
│ └── partials
│ ├── footer.html
│ ├── head.html
│ └── header.html
├── static
│ ├── css
│ └── js
└── theme.toml
archetypes
Archetypes zijn de Markdown-templates voor je site. Hierin specificeer je de front matter voor het type pagina. Standaard wordt er één archetype aangemaakt: default.md. Als je geen verschil hebt in type pagina’s is dit genoeg, en kun je in dit bestand de benodigde front matter definiëren. In een archetype kun je ook variabelen gebruiken, bijvoorbeeld om de actuele datum en tijd toe te voegen. Deze variabelen worden aangeroepen bij het aanmaken van een nieuwe pagina met hugo new <POST> en omgezet in tekst.
Voor Bits+Bites ziet het standaard archetype er zo uit:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags:
---
In de elementen tussen accolades worden variabelen en functies aangeroepen. De title wordt bijvoorbeeld gemaakt door de variabele .Name te gebruiken, daarin de streepjes te vervangen voor spaties en vervolgens de tekst om te zetten naar title case.
Ook is er een element draft. Zolang dat op true staat, zal de post niet getoond worden op de website. Je kunt deze posts wel renderen tijdens het ontwikkelen, door de Hugo server op te starten met -D als extra argument.
layouts
In de submap layouts wordt de html voor de verschillende pagina’s gedefinieerd. Voor het ontwerpen van de site is dit de plek waar het meest gebeurt. Onder layouts wordt bij het aanmaken van een thema automatisch de volgende mappenstructuur gegeneerd:
├── 404.html
├── _default
│ ├── baseof.html
│ ├── list.html
│ └── single.html
├── index.html
└── partials
├── footer.html
├── head.html
└── header.html
404.html
Soms kan het natuurlijk voorkomen dat een bezoeker op een pagina komt die niet meer bestaat. Om hier iets anders dan de standaard voor te laten zien, kan in 404.html hier een aparte layout voor worden gemaakt.
_default
De layouts in de map _default worden, zoals de naam ook suggereert, standaard als layout gebruikt bij het genereren van een nieuwe post. In deze map zitten 3 bestanden: baseof.html, list.html en single.html.
baseof.html kun je zien als de ruggengraat van de pagina. Hierin definieer je de basis waar de layout van list.html of single.html aan wordt toegevoegd. Als je hierin je head, header en footer definieert komen deze op alle pagina’s terug.
De volgende regel is nodig om informatie uit list.html of single.html te embedden:
{{ block "main" . }}
{{ end }}
list.html wordt gebruikt als overzichtspagina voor een verzameling posts van een bepaald type, bijvoorbeeld bites. In single.html definieer je vervolgens hoe een pagina met één post eruit komt te zien.
index.html
Naast de verschillende posts en pagina, heeft een website doorgaans ook een hoofdpagina. De layout hiervan wordt gedefiniëerd in index.html. Om content toe te voegen aan de hoofdpagina, kun je in de map content het bestand _index.md aanmaken. Informatie daaruit kun je ophalen via {{ .Content }}.
Doordat index.html ook wordt geïntegreerd in de baseof.html in de map _default is het niet nodig om de elementen daaruit toe te voegen..
Vormgeving anders dan default
Mocht je meerdere typen posts hebben kun je daar naast de _default map een andere map en eventueel ook een ander archetype voor aanmaken. Bits+Bites heeft bijvoorbeeld verschillende layouts voor bits - die de standaard-layout gebruikt - en bites. Voor een andere layout hoef je alleen de bestanden te genereren die daadwerkelijk anders zijn dan de default. Als in de submap voor het type bijvoorbeeld geen baseof.html wordt gevonden, gebruikt Hugo de baseof.html uit de map _default.
partials
In partials kun je componenten definiëren die meerdere keren op de website terugkomen, zoals bijvoorbeeld een header en een footer. Ook kun je het gebruiken om de code wat meer te structureren, door bepaalde grote afgebakende functies vorm te geven als een partial. Hierdoor blijft de layout zelf beter leesbaar.
Met deze code wordt een partial toegevoegd aan de layout:
{{ partial "<PATH>/<PARTIAL>.html" . }}
Een andere use-case voor het gebruik van partials is om bepaalde delen van de pagina te cachen, door een zogenaamde partialCached aan te roepen. Dit is handig bij bijvoorbeeld een logo, zodat deze niet voor elke pagina opnieuw hoeft te worden opgehaald van de server, maar gecached wordt in de browser. Het aanroepen van een cached partial gaat bijna hetzelfde als dat van een gewone:
{{ partialCached "<PATH>/<PARTIAL>.html" . }}
Hugo template syntax
In Hugo templates kun je veel variabelen gebruiken, maar ook transformaties op de data uitvoeren doordat het de Go template syntax gebruikt. De mogelijkheden hiervan zijn eindeloos, en het gaat voor deze post te ver om hier diep op in te gaan. De introductie biedt een goed startpunt. Daarnaast is de officiële Hugo documentatie rond variabelen en functies een erg handig naslagwerk.