Stork is a library for creating beautiful, fast, and accurate full-text search interfaces.

It comes in two parts. First, it's a command-line tool that indexes content and creates a search index file that you can upload to a web server. Second, it's a Javascript library that uses that search index file to build an interactive search interface that displays optimal search results immediately to your user, as they type.

Stork is built with Rust, and the Javascript library uses WebAssembly behind the scenes. It's easy to get started and is even easier to customize so it fits your needs. It's perfect for Jamstack sites and personal blogs, but can be used wherever you need to bring search to your users.

Quick Start Guide

It'll take less than five minutes to build the demo at the top of the page.

There are two steps involved. First, we'll add the HTML to a web page to turn an <input> tag into an interactive search bar that searches through a pre-existing search index. Afterwards, we'll customize the search index so you can search through your own content.

You can also see this demo on Codepen!

Adding the interface

Copy and paste the following to a new HTML file:

HTML

The Stork Javascript library takes over existing HTML that you include ahead of time. That way, you can define exactly how and where your input and search results appear on the page.

Each search interface has to have an input element and an output element. (The wrapper is only used by the basic.css theme we included above.)

<div class="stork-wrapper">
  <input data-stork="federalist" class="stork-input" />
  <div data-stork="federalist-output" class="stork-output"></div>
</div>

Your users will type into the input element and the search results will automatically appear in the output element.

Both the input and output elements must be registered to a certain index: that way, the Stork Javascript library knows how to associate a search index with the interactive elements on a page. The data-stork attribute lets you make that association.

Javascript

Right before the closing </body> tag, include the Stork script and register the index.

<script src="https://files.stork-search.net/releases/v1.6.0/stork.js"></script>
<script>
  stork.register(
    'federalist',
    'https://files.stork-search.net/releases/v1.6.0/federalist.st'
  )
</script>

The stork.register() function takes two arguments: the registration name from above, and the URL where the search index file can be found. Here, we're pointing to a public demo I developed: a search index for the Federalist Papers.

Now that the index is registered, the Stork Javascript library will load the search index and take over the HTML elements, letting you search through the

CSS

Stork is heavily customizable, and if you wanted, you could write CSS that makes the Stork output look exactly how you want. Alternatively, you can use one of the pre-existing themes to quickly spin up a polished look and feel for your search interface. Here, we're using the Basic theme:

<link 
  rel="stylesheet" 
  href="https://files.stork-search.net/releases/v1.6.0/basic.css" 
/>

Building your own index

Now that you have a search interface up and running on a webpage, I'll show you how to build the demo index we've been using: a search index for the first twenty Federalist Papers: essays written by three of the United States' founding fathers to promote the United States Constitution.

A Stork search index is built from a collection of documents, usually a set of files on your computer. To build a search index, you create a configuration file that defines that list of documents and specifies some metadata about each one. When you run the Stork command line application, you'll pass in that configuration file and Stork will build a search index based on the contents of those files and the specified metadata.

After you've installed the Stork command-line tool, download this .zip file. When you unzip it, you'll find a folder which contains a configuration file and a folder of text files. The configuration file looks like this:

This TOML file tells Stork how to retrieve, parse, and display the content. There are many different ways Stork can handle retrieval, parsing, and display; see the Configuration Reference to see all the options you can add to the configuration file or to each File object.

To test a configuration file while you're working on it, the Stork command-line tool includes a web interface that builds and presents an index from the configuration file. You can start the test interface via the following command:

$ stork test --input config.toml

Opening http://localhost:1612 in your browser will open a web page with your search index loaded. Here, you can test the search and adjust your index as necessary.

When you're ready, you can build the Stork index file with the command:

$ stork build --input config.toml --output my_index.st

This will create a new file at my_index.st. This file is your search index, and contains the displayed results for the query your user inputs. The file should be uploaded to a public place, and its url should be passed into the stork.register() function.