Stork, search for Static Site Generators

Last edit: Feb 28, 2023

In this first Bullet Point – on the first anniversary of Kaboom Shebang – we’ll look into search options for a static blog. This blog is built with Hugo and uses Stork.

Stork with Hugo

James Little created Stork, a websearch widget for static sites. It’s a polished, feature-rich, and well documented option.

At the time of writing the first beta of the v2.0 branch has just been released. More info about the new features

Generate index.toml

First, we have to create an index file. We can generate one by hacking into Hugo’s templating functionality.

Configure Hugo to output a JSON version of the homepage.

# config.toml
[outputs]
home = [ "HTML", "JSON", "RSS"]

Next, add an index.json file in the layouts folder with the following content:

Important : file paths are relative to the Stork CLI working directory (when executing).

[input]
html_selector = "article#main-contents"
{{ with .Site.GetPage "section" "bullet-points" }}
{{ range .Pages }}
{{ if not .Params.sitemap_exclude }}
[[input.files]]
path = "public/{{ .Params.url }}/index.html"
url = "{{ .Permalink }}"
title = "{{ .Title }}"
{{ end }}
{{ end }}
{{ end }}

This template will tell Hugo to build an index.json file with all the blogpost file paths and urls. It expects a url parameter in the blogpost frontmatter. With the html_selector property you can limit the index to a portion of the page.

Optionally, you can rename the extension to .toml. However, the file extension does not affect the CLI usage.

Build index

Now we’re ready to generate a .st Stork file. Download the Stork command line tool:

# download the command line tool
wget https://files.stork-search.net/releases/v1.6.0/stork-ubuntu-22-04
chmod 744 stork-ubuntu-22-04
# make sure to download for the correct OS

Run the tool with our index file and output to an .st file.

# file paths in index.toml are relative to the current working directory
./stork-ubuntu-22-04 build --input index.json --output index.st
# or, if you renamed the file
./stork-ubuntu-22-04 build --input index.toml --output index.st

WASM/JS files

We’re ready to integrate the frontend logic. Download and install the browser toolkit in your webpage.

  <!-- for example: -->
  <script src="https://your-url.com/stork.js"></script>
  <script>
    stork.initialize("https://your-url.com/stork.wasm")
    stork.register("yourIndexName", "https://your-url.com/index.st")
  </script>
</body>

Alternatives

Tinysearch is an alternative search toolkit also built with Rust and WASM. Should work with Zola, Hugo, and other SSGs.

Note: Tinysearch was not tested for this article.