Searching This Site

Today, i added a client-side search to this Pelican-generated website, which you can use from the 'Search' link in the navigation bar above. Here's a tidy summary of how i did it, in case you want to do something similar.

1. Survey the options. I asked Chaz (ChatGPT) to summarize the state of the art in client-side search, checked its recommendations, and chose Pagefind, an efficient, well-maintained, open-source, and easy-to-use JavaScript library that also has a Python wrapper.

2. Install Pagefind. Since Pagefind has a Python wrapper and good documentation, i could quickly install the library in my site's virtual environment in one command: uv add pagefind[bin].

3. Add the search bar. I put Pagefind's search bar user interface on a dedicated page by making a template called theme/templates/search.html with the contents

   {% extends "base.html" %}
   {% set active_page = "search" %}
   {% block title %}
       {{ super() }} > Search
   {% endblock %}
   {% block content %}
     <div class="blogItem">
       <h1>Search</h1>
   
       <!-- Pagefind UI (these files appear after indexing) -->
       <script src="pagefind/pagefind-ui.js"></script>
       <div id="search"></div>
       <script>
         new PagefindUI({
           element: "#search",
           resetStyles: false,   // Use my own CSS
           processResult: (res) => {
              // Change title style
             const u = new URL(res.url, location.origin);
             res.meta.title = decodeURIComponent(u.pathname);
   
             // Remove any detected/declared image so the UI won’t render a thumbnail
             delete res.meta?.image;
             delete res.meta?.image_alt;
   
             return res;
           }
         });
       </script>
     </div>
   {% endblock %}
   

   Then i linked to the page in the navbar.

4. Whitelist the search content. To return useful search results only, i configured Pagefind to index this site's main content only, that is, the pages, articles, and blog posts. More specifically, i inserted into each of those templates the block <main class="post" data-pagefind-body>...</main> just within the block {% block content %}...{% endblock %}.

5. Add the indexing command to Makefile and Gitlab CI config. To update Pagefind's search index after updating this site's content, i run the command uv run python -m pagefind --site public. For easy automation, i put that command into my Makefile and aliased it as search:

   PAGEFIND ?= python -m pagefind
   search-index:
       $(PAGEFIND) --site "$(OUTPUTDIR)"
   

   I run it like all other Make commands in this virtual environment, namely, uv run make search. Finally, since Gitlab CI builds this site from source whenever i push its master branch to Gitlab, i needed to add the indexing command to the script section of my .gitlab-ci.yml file like so

   script:
       # Use apt-get for Debian-based images
       - apt-get update && apt-get install -y make
       # Install dependencies
       - uv sync --frozen --no-cache
       - uv run make publish
       # Build Pagefind index
       - uv run make search-index
   

And that's all, folks. Site search now operational.