Sum it up, and be quick.

The Basics

• Go HTML Template - This is the basic language that is used to inject dynamic content and logic into an otherwise static HTML Document
• Hugo Templates - Hugo uses the Go HTML Template to structure the a site, from the home page, to sub pages, to navigation, all of the facets of a Huge Site are driven through these templates
• Hugo Clarity's Excerpt - This is the template I'm interested in, it renders the "Summary" that shows up on the root of this blog.

A Summary Example

There are definitely times when I will want to explicitly write the summary for a given post, but I do like automated things. The problem for me was that the autogenerated summary was pulling in the first few words from the post including the titles. The summary for the It Starts Here post reads "Hi, I'm Jeff What This site exists for me to collect...". You can read past the titles, but I wasn't super pleased with it. Something had to be done.

The summary is generated from the content of the It Starts Here post. It's a great feature of Hugo that it can autogenerate a quick summary, and display it in a list. This gives a quick way to surface content and doesn't require the author to create a separate abstract or summary.

Enough to be dangerous

I'm not familiar with the Go HTML Template format. I've used templating languages before like Handlebars or Mustache, so I'm familiar with the concept, but not expert enough to start running on my own. I needed some help

Step 1

Google is my friend when it comes to coding, although Github Copilot is slowly supplanting it. In this case because I didn't even know where to start. I searched and stumpled across this blog entry from Yihui Xie. It gave me the first bits I needed, spefically this line, which would use a regex to grab the contents of the first paragraph.

1{{ $.Scratch.Set "summary" ((delimit (findRE "(?s)(<p.*?>.*?</p>)" .Content) "[&hellip;] ") | plainify | truncate (default 200 $.Site.Params.summary_length) (default " &hellip;" $.Site.Params.text.truncated ) | replaceRE "&amp;" "&" | safeHTML) }}

Step 2

I needed ot figure out where to add this magic bit of code. I see that in the blog, Yihui Xie indicates that I need to update the default/list.html. Looking at what I've got in the Clarity Theme, I see the code block below.

The first thing I tried was to just paste the code, but that as expected didn't do what I was hoping. I needed to spend some time reading the templates. The first thing I noticed was the line - partial "archive". I saw there as a partials folrder, and inside that there was an archive.html file. When I read that template I saw there was the - partial "excerpt" line and a cooresponding excerpt.html file. When I examined that file, I saw something similar to what was in the blog post. I tried copy-paste-victory, but again it didn't work.

 1// list.html
 2{{ define "main" }}
 3  {{- partial "archive" . }}
 4{{ end }}
 5
 6// excerpt.html snippet
 7{{- $summary := truncate 320 .Summary }}
 8{{- if .Params.summary }}
 9  {{- $summary = .Params.summary }}
10{{- else if .Params.abstract }}
11  {{ $summary = .Params.abstract }}
12{{- end }}
13{{ if not ( strings.Contains $summary "<p>" ) }}
14  <p>{{ $summary | markdownify }}</p>
15{{ else }}
16  {{ $summary | markdownify }}
17{{ end }}

Step Win

Once again I needed to read the template, and think about what it was doing. I saw the line {{- $summary := truncate 320 .Summary }} and realized it was setting a $summary variable with the truncated value of the .Summary This looked a lot like the work the {{ $.Scratch.Set "summary" ... line was trying to do. So I took the blog line, and merged it with the line in the excerpt.html file to create the line below - and Win. I now have an autogenerated Sumamry that is based on the first paragraph of a post. So much nicer.

1 {{- $summary := ((delimit (findRE "(?s)(<p.*?>.*?</p>)" .Content) "[&hellip;] ") | plainify | truncate (default 200 $.Site.Params.summary_length) (default " &hellip;" $.Site.Params.text.truncated ) | replaceRE "&amp;" "&" | safeHTML) }}

Step Override

Thankfully Hugo makes it pretty simple to override a theme. I created a local /layouts/partials/excerpt.html and there you have it - a clean summary.

Wrap

In this case it definitely helped to have some experience with templating, it let me walk the code a little easier, but really it's mostly about finding other examples, and just tinkering. There's a good chance, that what I've done isn't correct, but that's okay, I'm learning, and part of that process is just trying things. In this case most of what I tried didn't work. When I got stuck I read the code, thought about it, and came up with a new switch flip. So far I'm pretty happy with the outcome.

Even in my professional career, it's not uncommon for me to just try my way to a conclusion. I do have the advantage of having competent peers that can correct me, but it's definitely a viable approach to solving the problems you encounter.

QOTD

“I'm smart enough to know that I'm dumb.” ― Richard Feynman