Notes on the HugoPlate theme

Table of Contents

Overview
#

This note outlines how the example site for HugoPlate works, and the Hugoplate theme. It identifies how the example site can be modified to a user site. It is perhaps useful for a reader who is attempting to use a Hugo example site/theme for the first time

Home Page
#

The content root directory /content/english shows that the markup home page is provided by -index.md. All layout is provided by the theme, in the directory /themes/hugoplate/layouts. The matching template is index.html, and as there is a template baseof.html in the _default directory that is subsequently applied.

Specifically, the templates are applied to the Page object generated from the file _index.md. That file consists only of front-matter, defining banner and features.

The template index.html specifies three pieces of the home page.

A banner piece. It does this by accessing the components of .Params.banner, which were set by the front-matter of _index.md.
a features piece. It does this in a analogous fashion, by accessing .Params.features.
A testimonials piece. It does this by

{{ with site.GetPage "sections/testimonial" }}

This uses the GetPage method on the site object, to reference the Page object associated with the testimonial.md content file.

In each case, the detailed HTML is specified. Finally, no output is actually written. Rather, the entire specification is defined to be a template named main.

The template baseof.html is now applied to the home Page object. It generates a production-quality web-page. In visual terms it specifies a header and a footer (which will be common to all web-pages in the site. The content of the page is generated by applying the main template at the appropriate place. This standard device is used to economically generate all web-pages.

about directory
#

The markup file is _index.md while the template file is provided by the theme, namely layouts/about/list.html.

Need to explain how the matching directory is created in /public and how file index.html is created.

The markup file involves some front-matter and some straight text.

The template can be shown in full:

{{ define "main" }}
  <section class="section-sm">
    <div class="container">
      <div class="row justify-center">
        <div class="md:col-10 lg:col-7 text-center">
          {{ partial "image" (dict "Src" .Params.image "Context" .Page "Alt" .Title "Class" "mx-auto mb-6" "Size" "200x200") }}
          <h2 class="h3 mb-6">{{ .Title }}</h2>
          <div class="content">{{ .Content }}</div>
        </div>
      </div>
    </div>
  </section>
{{ end }}

This templates writes out the specification of an image, and a heading (both derived from the front-matter). It then writes the text of the markup file. This specification is defined to main, rather than actually being carried out.

The processing then follows exactly as for the home-page. The template file baseof.html is applied to the page object. The same header and footer is generated, but now with a different middle section corresponding to main.

authors directory
#

_index.md has the same effect as the about directory.

Each of the three content files are processed by

creating a sub-directory
generating an index.html file by applying the template xxx to the content file.

Categories and Tags
#

Explain

how each blog post is labelled in the front-matter with category terms and tag terms. This is not restricted to blog posts
how Hugo automatically creates directories /categories and /tags, and populates them
these can then be made available in menus etc by templating

blog directory
#

The processing of index.md using the template layouts/blog/list.html is more complicated.

  <section class="section">
    <div class="container">
      <div class="row gx-5">
        <!-- blog posts -->
        <div class="lg:col-8">
          <div class="row">
            {{ $paginator:= .Paginate .RegularPages }}
            {{ range $paginator.Pages }}
              <div class="md:col-6 mb-14">
                {{ partial "components/blog-card" . }}
              </div>
            {{ end }}
          </div>
          {{ partial "components/pagination.html" . }}
        </div>
        <!-- sidebar -->
        <div class="lg:col-4">
          <!-- widget -->
          {{ $widget:= site.Params.widgets.sidebar }}
          {{ partialCached "widgets/widget-wrapper" ( dict "Widgets" $widget "Scope" . ) }}
        </div>
      </div>
    </div>
  </section>

There is a row of two components.

The first is a summary of all the blog posts. This is done by calling the Paginate operator on the collection of blog page objects. This breaks them into groups of 2 (set in xxx), creates a directory page and writes the rendered objects into sub-directories 1, 2. It writes the first group onto the page. It then puts a menu underneath.

The second component is a sidebar, defined in xx

[widgets]
sidebar = ["categories", "tags"]

This is processed by a widget template.

The processing of the content files is standard. A directory is created for each blog page, and the rendered page written to index.html in that directory.

pages directory
#

Contrary to current practise, this contains neither a _index.md or a index.md file. It is a page bundle, because it is a first-level directory. Hence it is processed by a list template (in _default).

The two content files are processed in a strange way. Directories are created at level one, rather than as subdirecries of /page, and the content rendered into index.html. Maybe it is a convention remaining from an early version of Hugo.

sections directory
#

This is similar to /pages. In this case the content files are not rendered, because of a front-matter specification.

# don't create a separate page
_build:
  render: "never"

CSS Styling
#

The homepage index.html contains the fragment

<link
  href="/css/style.css"
  integrity=""
  rel="stylesheet" />

This specifies that the external document referenced by the URL is a stylesheet for the homepage. The question is: how does the HugoPlate template generate the contents of the file style.css?

The work is done by the template style.html (provided by the theme in partials/essentials). The key statements are

{{ $styles := slice }}
{{ $styles = $styles | append (resources.Get "scss/main.scss" | toCSS) }}
{{ $styles = $styles | resources.Concat "css/style.css" }}
{{ $styles = $styles | resources.PostCSS }}
<link
  href="{{ $styles.RelPermalink }}"
  integrity="{{ $styles.Data.Integrity }}"
  rel="stylesheet" />

Informally each step does the following:

$styles is an empty slice (list).
The file main.sccs is read and is appended to the list. Each element of the list is transpiled to CSS. The file main imports five other scss files in the theme, goes through the Hugo modules that have been imported (in xxx) and imports their scss components (if any) and then imports the contents of assets/scss/custom.scss. This allows customisation if the example site is developed.
The elements of the list are concatenated and stored in resources, with the indicated target path.
styles is then processed by plugins (see postcss.config.js). The styling so far has made reference to Tailwind classes. The processing arranges that only the classes actually referenced are physically imported.
The method RelPermalink has the side effect of writing the contents of the variable to the indicated file in the public directory.

Making it all work is an impressive demonstration of theme coding and Hugo processing.

Overview#

Home Page#

about directory#

authors directory#

Categories and Tags#

blog directory#

pages directory#

sections directory#

CSS Styling#