Moved From Papermod to Blowfish

Update (2026-07-24) : RSS updates, Miscellanea, some editing.

I changed my blog theme from Papermod to Blowfish.

Why move to Blowfish?

#

Papermod, to my mind, is perfection. And I outgrew it. That’s all there is to the why.
Papermod caters to the needs of a blog, and I think my blog is slowly turning into a multi section website.
I want menus, and possibly submenus and Papermod does not do them.
The finished outcome, while not as pretty and uniform as the old Papermod site, makes writing and managing it all, much simpler.

Blowfish specific things for future Jason to note.

#

Big Picture things

#

• The theme does a lot. Most of which I don’t think I need.¹
• The aim is to match what my site looked with Papermod, as closely as possible.
• Everything CSS is in assets/css/custom.css, rather than multiple CSS files as it was with Papermod.
• Pagefind powers search on the site. The inbuilt search is disabled in main.toml.
• Footnotes use Littlefoot; so they appear as popups, and the need to scroll up and down the page is reduced.

Configuration

#

Blowfish separates everything out in its config. Lots of toml files in there.

• Base config is in hugo.toml, theme parameters are in params.toml, menus in menus.XX.toml and language + translation related stuff is in languages.XX.toml ²
• main.toml sets the theme, the baseURL and I’ve added a section to limit RSS entries to only the last 50 items.
• The author parameters along with the social link set, as well as the logo, are in languages.XX.toml. I have duplicated them. One for EN and one for FR. The logo that it requires, is in the assets/logo directory.
• Menus and submenus in menus.XX.toml. Duplicated. The English menus have English names and the French, French ones.
• Parameters; the header is set to basic. Every other option creates a sticky header of some sort. Lots of other changes. Most are self explanatory. Turned off “Hero” options everywhere, to stick to a plain, basic layout as much as possible.
• My split of the various configuration files for environments (base, development & production) have stayed the same with no changes.

Content Structure

#

• Directories and subdirectories for each section.
• Make sure each section has a corresponding index.XX.md for static pages or _index.XX.md for list pages. This, I think (but am not sure) has fixed my old, nagging issue of page navigation overflowing. I would keep going next, in the Talks section for example, and when I reached the end, it would show me another entry from some other section. Now the front/back buttons stay restricted to the section they are in.

Archetypes

#

• All the archetypes have been slightly tweaked. They now also include a template line for an image. It uses the theme’s figure shortcode for images.

i18n (Internationalisation)

#

• The internationalisation options are easier here. Just defining a term somewhere and then referring to it here just works.
  For e.g., I use search_placeholder as a term in the search layout and then in i18n/en.yaml I have, search_placeholder: "Search for something …" while i18n/fr.yaml gives the same term a different spin, search_placeholder: "Rechercher des articles …"

Layout Overrides

#

RSS

#

• Have tweaked the RSS layout a teensy bit. My version is in layouts/_default/rss.xml, which includes the full text of the post, instead of just a summary.

<!-- <description>{{/* .Summary | transform.XMLEscape | safeHTML */}}</description> -->
     <description>{{ .Content | transform.XMLEscape | safeHTML }}</description>

• Have restricted RSS feed generation for posts in the Notes and Miscellanea section. They won’t appear in the RSS feed unless I want them to. Most of them are just streams of consciousness, to help me get on with my day. Only a few are exceptions, that I want published.
  I even disable sitemap generation for those “important to me, but useless for thee” posts with this bit of metadata in each post³

sitemap:
  disable: true

• So I have then taken advantage of this fact, to exclude these posts from having entries in the RSS feed, by telling Hugo to only look at posts where such a key does not exist; which basically, is everything else.

<!-- {{/* range $pages */}} -->
     {{ range where $pages "Sitemap.Disable" "ne" true }}

Search

#

• This pulls in the script and the styles for Pagefind, which I use for searching the blog. Layout is in layouts/_default/search.html.
• Also note, then when working on search locally, first create an index with pagefind and move it to the static folder because our normal way of working is to render it all in memory.
  • do a hugo build
  • then do pagefind_extended --site public
  • then mv public/pagefind static/pagefind
  • then rm -rf public
  • and then start the hugo server like we normally do

Littlefoot

#

• Footnotes are powered by Littlefoot. Have used layouts/partials/extend-footer.html to pull in the Littlefoot script and layouts/partials/extend-footer.html to grab the CSS.

Redirect

#

• An old redirect template to redirect from one section to the other is still in place in the layouts/redirect directory

Shortcodes

#

• Most of the old shortcodes made it over. Retired my image and caption shortcodes in favour of using Blowfish’s version. Also created an hsgallery shortcode, so that I could continue using my old Hugo Shortcode Gallery to create image galleries. The gallery shortcode conflicts with Blowfish’s own, which I don’t like and so won’t use.

Static + Tools

#

• Fonts and Littlefoot reside in the static directory, along with all my images.
• There’s also a tools directory which contains the Pagefind binary. This does not get published obviously. But the Forgejo action uses this to generate an index for the site and then sends the whole thing off to the VM.

Themes

#

• Contains Blowfish and Hugo Shortcode Gallery, added as git submodules. I dropped Hugo Admonitions, because Blowfish has them already.

CSS

#

All in assets/css/custom.css

1. Import fonts: Valkyrie for the site and Source Code Pro for code.
2. Tweaked the Janusworx up left on my site, and changed all the nav bar items to use Valkyrie Caps.
3. Dark mode links were not contrasty enough. So changed the colour and added an underline on hover.
4. Added a class to the figure tag, so I could center the pics I use.
5. Added an indent to the numbered list items on the Annual Book List pages, so that the numbers stay under each month.
6. Style littlefoot footnotes, so that the button is slightly smaller and higher, and the notes use Valkyrie, along with a couple of other tiny tweaks.
7. Style the Blowfish box, and the results, on the search page
8. Main thing to note. Use !important; liberally. Changes don’t always cascade down correctly.

Miscellanea

#

Go Templates:

#

• Use ```go-html-template as the language hint to the code fence to display Go template code correctly. (like I needed to in this post for e.g.)
• If it is pure Go Template stuff with little to no html, another alternative is ```go-text-template
• I could not just comment out Go template code with HTML comment markers <!-- -->. The Hugo live server kept crashing on me with weird EOF errors, until I figured this out. The Go template block needs a comment marker inside the the {{ … }} section like so, {{/* … */}}.
  E.g. {{/* range $pages */}}