Customizing the Relearn theme

Using Themes
1

Thank you for this example. The content adapter feature seems very useful, I’ve been using hugo for a while and was just asking colleagues if they were aware of “something like hugo, but that can generate pages from data” and they pointed out the 0.126 release notes!

I’m excited about this feature, but I can see it means I will need to get much more familiar with how templates work. As @jmooring commented, it seems to create a “blending” of content and templates. Which is fine, but it means users like me can no longer be blissfully ignorant of templates.

Which brings me to my question. Using content adapters means writing specialized new templates – e.g. from your example, layouts/books/single.html. What I don’t understand is, what is the best-practice way to write a new template, while using a theme?

Your simple example renders plain-jane HTML pages – would you consider updating it to show how you would write the layouts/books/single.html template, while using, say, the relearn theme? How does one gracefully “extend” the themes/relearn/layouts/_default/single.html.

2

You can overwrite theme templates by placing them in the layouts directory of your root project.

Templates can live in either the project’s or the themes’ layout folders, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.

e.g.

themes/relearn/layouts/_default/single.html

will be overwritten by

layouts/_default/single.html

Copy the theme’s single.html into the layouts directory and make changes as needed.

1 Like
3

Thank you for the help. I understand the principle of template lookup order, but what I don’t understand how to do template inheritance gracefully.

The relearn theme’s single.html template (themes/relearn/layouts/_default/single.html) just says this:

{{- partial "_main.hugo" . }}

…which I gather is a reference to this partial: themes/relearn/layouts/partials/_main.hugo… which contains:

{{- partialCached "page-meta.hugo" . .RelPermalink }}
{{- $outputFormat := partial "output-format.hugo" . }}
{{- partial "output-partial.hugo" (dict "base" "header" "page" . "parameter" . "outputFormat" $outputFormat) }}
{{- if not .File }}
  {{- partial "output-partial.hugo" (dict "base" "body" "page" . "parameter" (dict "page" . "content" (partial "output-partial.hugo" (dict "base" "initial" "page" . "parameter" . "outputFormat" $outputFormat))) "outputFormat" $outputFormat) }}
{{- else }}
  {{- partial "output-partial.hugo" (dict "base" "body" "page" . "parameter" (dict "page" . "content" (partial "output-partial.hugo" (dict "base" "content" "page" . "parameter" . "outputFormat" $outputFormat))) "outputFormat" $outputFormat) }}
{{- end }}
{{- partial "output-partial.hugo" (dict "base" "footer" "page" . "parameter" . "outputFormat" $outputFormat) }}

…and then themes/relearn/layouts/partials/output-partial.hugo has this:

{{- $base := .base }}
{{- $page := .page }}
{{- $parameter := .parameter }}
{{- $outputFormat := .outputFormat }}
{{- if not $outputFormat }}
  {{- $outputFormat = partial "output-format.hugo" $page }}
{{- end }}
{{- $suffix := partialCached "output-suffix.hugo" $page $page.RelPermalink $outputFormat }}
{{- $f := printf "/layouts/partials/%s.%s.%s" $base $outputFormat $suffix }}
{{- if or (not $outputFormat) (not (partialCached "fileExists.hugo" $f $f)) }}
  {{- $f = printf "/layouts/partials/%s.%s" $base $suffix }}
  {{- if partialCached "fileExists.hugo" $f $f }}
    {{- partial (printf "%s.%s" $base $suffix) $parameter }}
  {{- end }}
{{- else }}
  {{- partial (printf "%s.%s.%s" $base $outputFormat $suffix) $parameter }}
{{- end }}

…but at this point, I already feel like I’ve take a wrong turn!

I’m coming at this from years of working with jinja2/django/flask style templating, and I was thinking I could “extend” the relearn “single.html” template and then override blocks to write custom content. But when I look at the above relearn template files, I don’t see any obvious ways to override single.html: How can I gracefully use this template, but, like, write my own {{ define "main" }}...{{ end }}} block?

I know this must be a noob question for those familiar with writing hugo templates, but I bet a lot of hugo users, like me, have never needed to dig too deeply into this. A worked example, with a theme, would be really helpful.

Thank again for your help!

4

That might be a better question for the theme author, since that’s a complex and somewhat unusual layout.

5

Many/most Hugo themes use a baseof.html with blocks but the “relearn” theme that you are using does not. It has old roots and use a more custom system.

6

I have not used this feature in any project yet but I think you misunderstood that comment.

To implement content adapters you need to create a _content.gotmpl. A content template, this is the template refered to.

If you use the content adapter to generate content that fit with your theme you can continue using the theme as is.

1 Like