Papermod on Janusworx

Moved From Papermod to Blowfish

feedback@janusworx.com (Mario Jason Braganza) — Fri, 24 Jul 2026 08:30:00 +0530

Intended Audience

Me.
This is a sorta-kinda living document, a record of my idiosyncratic decisions to first move to, and then bend the Blowfish theme to my needs.

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

Blowfish theme logo

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

Import fonts: Valkyrie for the site and Source Code Pro for code.
Tweaked the Janusworx up left on my site, and changed all the nav bar items to use Valkyrie Caps.
Dark mode links were not contrasty enough. So changed the colour and added an underline on hover.
Added a class to the figure tag, so I could center the pics I use.
Added an indent to the numbered list items on the Annual Book List pages, so that the numbers stay under each month.
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.
Style the Blowfish box, and the results, on the search page
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 */}}

Feedback on this post?
Mail me at feedback at this domain.
P.S. Subscribe to my mailing list!

famous last words! ↩︎
XX is the language code. I have EN for English and FR for French. So menus.fr.toml for e.g. ↩︎
I have modified the notes archetype, so this is always pre filled and set. ↩︎

You Can Now Search this Blog

feedback@janusworx.com (Mario Jason Braganza) — Tue, 23 Jun 2026 14:24:24 +0530

Intended Audience

Me. In case I want to retrace the big idea tomorrow

tldr: https://janusworx.com/search
#

Being the lazyass that I am, I used to depend on search engine indexes to find something on my own blog. (First google, then DuckDuckGo.)
Kushal, having https://search.kushaldas.in/ has always made me jealous though.
And now, the days of finding something relevant on my blog, on the first search are long gone. Search engines today are a pale shadow of what they used to be. The current load of crap actually makes me long for the days of Altavista!

So, I decided to get off my butt, and go do something about it, because everytime I want something, my blog is one of the first places I search.
For e.g. when writing this post, I needed to look up how to add line numbers to my code blocks. Search helped me find it :)

I went to the Hugo website and decided to implement the first search tool¹ they suggested: Pagefind.
Well, I did that since Pagefind took care of the only thing I’m anal about. It keeps everything local and under my control. If not, I’d have kept looking for something else.
What it (Pagefind) does, is parse the site, Hugo builds for me, and create a search index along with some more goodies (an api for search as well as UI components) in a bundle. The rendered html and the bundle together are now the artifact that my site is made up of.

The Plan
#

Get Pagefind and install it into a tools subdirectory in my blog’s directory, so I always have it handy (and the Forgejo action can get its grubby paws on it when it wants to run the publishing workflow)
Create an entry in my menu, so I can go clicky to a search page.
Create said search page.
Make search work.
Make the page resemble the rest of the blog as much as possible.

Installing it and wiring it all up
#

1. Installation
#

This is the easy part. Pagefind is a single binary, which I shoved into the tools subdirectory.

2. Creating an entry for search in the navigation menu
#

I edited my Hugo config (mine is called hugo.yaml), and added search as a menu item.
More shifted downwards, as did its weight.

menus:
 main: # elided config
 - identifier: search
 name: search
 url: /search
 weight: 60
 - identifier: more
 name: more …
 url: /more/
 weight: 70

3. Creating the search page.
#

This was a two step process.

a. I needed a placeholder page that I could render some layout (a template) into.
#

This was search.md which lives in my content directory. This is all it contains …

1
2
3
4
5


---
title: Search
layout: search
url: /search/
---

See the key that says layout on line 3? This is looking for a layout called search which is what we now create …

b. Creating the search layout.
#

Papermod already ships with a layout called search. Which I did not want, because it is meant for use with another local search engine called lunr.js.
Hugo can override whatever file your theme provides, by letting you create your own versions of said file in the layouts directory. Hugo will then look at that instead of the theme’s file.
Over the years I’ve gotten dangerous enough by using Hugo’s lovely channel for discourse. Between that, and Hugo’s documentation as well as Pagefind’s own help page, I rustled up a layout file called search.html which lives in my layouts/_default directory. This is what it contains …

{{ define "main" }}

<link rel="stylesheet" href="/pagefind/pagefind-component-ui.css">
<script type="module" src="/pagefind/pagefind-component-ui.js"></script>


<div class="main">
 <article class="post-single">
 <header class="post-header">
 <h1 class="post-title">{{ .Title }}</h1>
 </header>

 <div class="post-content search-content">
 <pagefind-searchbox id="searchbox"
			 autofocus="true"
			 shortcut="/"
			 placeholder='{{ i18n "search_placeholder" }}'>
 </pagefind-searchbox>
 </div>

 </article>
</div>

<script>
 // we’re waiting for the pagefind-searchbox component to be registered 
 customElements.whenDefined('pagefind-searchbox').then(() => {
 const box = document.querySelector('pagefind-searchbox');
 // shadowRoot input, or a delegatesFocus component may expose it differently
 const tryFocus = () => {
 const input =
 box.shadowRoot?.querySelector('input') ??
 box.querySelector('input');
	// search for input boxes in two different ways above
	// and if it finds one focus it below
 if (input) {
 input.focus();
 } else {
 // component rendered but input not yet in DOM — wait one more frame
	 // wait for the shado
 requestAnimationFrame(tryFocus);
 }
 };
 // try one more time
 requestAnimationFrame(tryFocus);
 });
</script>

{{ end }}

This creates the box on the search page, ready to take input and show results.

Update (2026-06-24): The eagle eyed amongst you, have figured out this code has changed between yesterday and today. I used Pagefind’s documentation to simplify what I had yesterday even more and then got one of the llms to write a script that focuses the input box when the page loads, so that we can just start typing in whatever we need to search.

4. Make the page resemble the rest of the blog as much as possible.
#

Doing things a bit out of order and finishing up with the page first.
Leaned on Pagefind’s docs as well as Chatgpt, Claude and Gemini for this part to create a CSS file, that looks pretty native to my blog. I’ve called it include-pagefind.css and it lives in the assets/css/extended subdirectory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


:root {
	/* you don’t really need to use `pf-font`, 
	if you don’t have a custom font.
	for some reason, it wouldn’t render the font I specified here, 
	so I forced it with `!important` */
 --pf-font: your-font-name-here !important; 

 --pf-text: var(--primary);
 --pf-text-secondary: var(--secondary);
 --pf-text-muted: var(--secondary);

 --pf-background: var(--theme);
 --pf-border: var(--border);
 --pf-border-focus: var(--primary);

 --pf-hover: var(--tertiary);

 --pf-mark: var(--primary);

 --pf-border-radius: 8px;

 --pf-input-height: 48px;
 --pf-input-font-size: 1rem;

 --pf-result-title-font-size: 1rem;
 --pf-result-excerpt-font-size: 0.90rem;

 --pf-shadow-sm: none;
 --pf-shadow-md: none;
 --pf-shadow-lg: none;
}


.search-content {
 margin-top: 2rem;
}

pagefind-input {
 display: block;
 margin-bottom: 1.5rem;
}

pagefind-summary {
 display: block;
 margin-bottom: 1rem;
}

pagefind-results {
 display: block;
 margin-top: 1rem;
}


pagefind-results a {
 text-decoration: none;
}

pagefind-results article {
 border: 1px solid var(--border);
 border-radius: 8px;
 padding: 1rem;
 background: var(--entry);
}

pagefind-results article:hover {
 background: var(--tertiary);
}

5. Make Search Work.
#

This is a 3 step process

a. Build the blog.
#

Easy peasy. hugo build and we have our blog rendered in the public subdirectory.

b. Get Pagefind to create its index in the build directory.
#

This is easy as well.

./tools/pagefind --site public

and Pagefind creates a pagefind subdirectory in our public directory where it creates its search index after reading all the html.
All I need to do now, is just …

c. Publish!
#

Ok, I lied a teensy bit. I don’t have to do steps a. and b. because they are part of step c.
The Forgejo action checks out my committed files, pulls in Hugo from a private package repo, builds the site, then runs Pagefind to generate the index² and finally uses rysnc to sync it with the VM. Here’s the relevant section of the action.

# lots of stuff elided …

jobs:
 build-and-deploy:
 runs-on: my-big-box

 env:
 HUGO_VERSION: ${{ vars.HUGO_VERSION }}
 steps: # lots of snipped stuff …
 - name: Checkout the website repo
 uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 1
 
 - name: Build website with Hugo
 env:
 HUGO_ENVIRONMENT: production
 run: |
 hugo \
 --gc \
 --minify

 - name: Build the Pagefind search index
 run: |
 tools/pagefind \
 --site public

I thought the indexing would take a lot of time and was hesitant to use it as part of a regularly run Forgejo action workflow, but several runs show that the index generation only increases the time by at a couple of seconds at most. This is amazing!

Now I can search my own words, on my own blog, to my hearts content!

Feedback on this post?
Mail me at feedback at this domain.

P.S. Subscribe to my mailing list!

as on 2026-06-23 ↩︎
this is why i chucked it into the tools subdirectory and committed it. ↩︎

Papermod on Janusworx

Moved From Papermod to Blowfish

Why move to Blowfish? #

Blowfish specific things for future Jason to note. #

Big Picture things #

Configuration #

Content Structure #

Archetypes #

i18n (Internationalisation) #

Layout Overrides #

RSS #

Search #

Littlefoot #

Redirect #

Shortcodes #

Static + Tools #

Themes #

CSS #

Miscellanea #

Go Templates: #

You Can Now Search this Blog

tldr: https://janusworx.com/search #

The Plan #

Installing it and wiring it all up #

1. Installation #

2. Creating an entry for search in the navigation menu #

3. Creating the search page. #

a. I needed a placeholder page that I could render some layout (a template) into. #

b. Creating the search layout. #

4. Make the page resemble the rest of the blog as much as possible. #

5. Make Search Work. #

a. Build the blog. #

b. Get Pagefind to create its index in the build directory. #

c. Publish! #

Why move to Blowfish?
#

Blowfish specific things for future Jason to note.
#

Big Picture things
#

Configuration
#

Content Structure
#

Archetypes
#

i18n (Internationalisation)
#

Layout Overrides
#

RSS
#

Search
#

Littlefoot
#

Redirect
#

Shortcodes
#

Static + Tools
#

Themes
#

CSS
#

Miscellanea
#

Go Templates:
#

tldr: https://janusworx.com/search
#

The Plan
#

Installing it and wiring it all up
#

1. Installation
#

2. Creating an entry for search in the navigation menu
#

3. Creating the search page.
#

a. I needed a placeholder page that I could render some layout (a template) into.
#

b. Creating the search layout.
#

4. Make the page resemble the rest of the blog as much as possible.
#

5. Make Search Work.
#

a. Build the blog.
#

b. Get Pagefind to create its index in the build directory.
#

c. Publish!
#