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. ↩︎

Pagefind on Janusworx

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! #

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!
#