Hugo content summaries and I have a complicated relationship. Rather, the design decisions behind the Hugo .Summary page variable intrigue me.
I’m going to tell you how I render my post summaries on my site front page, main blog page, and many of my various section pages, but not today. Today I’m going to write many words about why I had to come up with my own way of rendering Hugo post summaries. I apologize, but it has to be done.
By design, using .Summary to display a post summary1 strips out all the HTML formatting. The summary will appear as one block of text, regardless of paragraphs and line breaks in the original text. In addition, any images or footnotes or any other non-plaintext will be removed.
This is … an interesting choice. And not, I suspect, what most people want. It’s definitely not what I want. I want posts that look normal but aren’t displayed in their entirety unless they just so happen to be shorter than my predetermined desired summary length. It’s trivial to strip HTML from text when it’s present, but much harder to put it back when it isn’t.2
Hugo does provide ways to generate summaries that do not remove HTML, but they’re manual and onerous, to be blunt.
The three ways Hugo lets you generate post summaries are:
I’ve already detailed my issues with option 3, automatic summary splitting, at the start of this post.
Manual summary splitting is done by inserting an html <!–more–> tag at the point you want the split to take place, and that’s something I never want to be bothered with. I want my list page summaries to be generated automatically, not for me to have to manage the summary split location while I’m writing.
How posts are displayed on the site should be as removed as possible from my responsibilities as a writer. The site should handle that. Me having to manually remember to and decide where to insert a <!–more–> tag is a bit silly in ways that annoy my automation-loving self. It also makes it harder for any collaborators, a problem I don’t have, but many sites do.
I’ll admit to shaking my head at the revelation in the Hugo Community discussion on the topic that people are putting the tag into their archetypes and then creating their posts by manually editing their templates. The whole point of me using an app like iA Writer is because it has the writing experience I want, and I don’t want to have to write text in Hugo templates. The site shouldn’t dictate how I write, it should just put whatever words I dictate on display when I’m done.
Since the <!–more–> tag needs to be located where you want the break to occur, it’s either highly manual, or it requires a shortcut or script to count characters and insert it. However, I want to avoid breaking HTML tags so that I don’t have a hanging blockquote tag way up the page that throws all following post summaries into blockquote, for example, so doing it through automation is not trivial. And Hugo already has a beautiful truncate function that worries about the HTML tags for you when chopping the .Content string. Using it is advisable.
The same consideration applies to the front matter summary variable method. Neither generating a differing set of text to stuff into a front matter summary variable nor taking part of the existing text and putting that in there appeals to me at all. The former isn’t what I want, and the latter has all the HTML breaking issues that <!–more–> unless it’s done manually. Again – not what I want. If I have to be in Hugo templates just to write a blog post, something or someone has failed.
At this point, over 550 words into this Summary Manifesto, you may find yourself wondering “could be it be that he has a solution that works for him, and that could work for me too?”
I do. But first let me preface it by saying:
When it comes to Hugo, since I’m still coming out of the clubbing phase and trying my hardest to enter the delicate instrument phase, I often do things that are suboptimal or unnecessary (duplicates Hugo functionality I’m unaware of). I hope I’m doing better at both of those as I learn more, but it happens. So caveat emptor and all that.
Next time, my Sweet Summary Solution.3