May 02, 2020

Custom hugo theme

hugo linux

Top level folder layout

The available themes for a Hugo CMS instance are located in the theme folder. Picking a theme is done by The name of the directory containing the theme is also the theme name, if you want to use it in your hugo instance, you have to configure it as theme: <theme name> in hugo’s configuration file, which is usually config.yaml or config.toml in hugo’s top level directory.
You can run a hugo instance without a theme by hosting the theme folder content in hugos top level directory.

A theme folder has the following content:

  theme_name
    archtypes
    assets
    layouts
    statics
    theme.toml

The easy parts

Most of subdirectories host static content or templates:

  • archtype
    home of the templates, when using hugo new posts/2020-05-02somethingsomething.adoc the content of this directory is used to create a new file
  • assets
    contains input for hugo’s asset pipelines, e.g. css files that will be minified or svg files for including as partials
  • layouts
    contains the layouts for rendering the site or parts of single or list pages
  • statics
    static content like JavaScript, css or webfonts to be included in the final version of the site
  • theme.yaml
    the main config file for the theme

The layout folder

This folder contains the fragments and page rendering templates that are used to render different parts of the site.

  layouts
    _default
       baseof.html
       list.htnl
       single.html
    partials
       footer.html
       head.html
       main.html
       row.html
    404.html
    index.html

The top level entry point for rendering is the baseof.html file, it includes partials and the main block.

<!DOCTYPE html>
<html lang="en-US">
{{ partial "head.html" . }}
  <body>
    {{ partial "header.html" . }}
    {{ block "main" . }}{{ end }}
    {{- partial "footer.html" . -}}
  </body>
</html>

The partials head, header and footer are inserted from the partials directory. The source for the main block can be another layout file, the simplest version is the single.html which renders the content of a single post:

{{ define "main" }}
  <main>
    <div class="container">
      <!-- single.html -->
      <h1 id="title">{{ .Title }}</h1>
      {{ .Content }}
    </div>....
  </main>
{{ end }}

the content is included at the {{ block "main" . }} position in the baseof.html template.

URL to file mapping

The following table is giving an overview which main block is used for which URL.

URLfile used as {{ block "main" . }}
/theme/layouts/index.html
/some/unknown/url.htmltheme/layouts/404.html
/posts/2020-05-02-existing-article/theme/layouts/_default/single.html
/posts/

theme/layouts/posts/list.html
theme/layouts/_default/list.html

/tags/

theme/layouts/tags/list.html
theme/layouts/_default/list.html

For more details of the lookup hierarchy see: https://gohugo.io/templates/lookup-order/

File dependencies

Diagram