Stork

Impossibly fast web search, made for static sites.

Search the Federalist Papers*:

*Well, just the first twenty.

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

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.

Latest version:

v1.3.0

Released on Nov 23, 2021

View on Github →

Quick Start Guide

Getting started with Stork is quick. 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.

Adding the interface

Copy and paste the following to a new HTML file:

index.html
1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8" />
5 <title>Federalist Search</title>
6 <link rel="stylesheet" href="https://files.stork-search.net/basic.css" />
7 </head>
8 <body>
9 <div class="stork-wrapper">
10 <input data-stork="federalist" class="stork-input" />
11 <div data-stork="federalist-output" class="stork-output"></div>
12 </div>
13
14 <script src="https://files.stork-search.net/stork.js"></script>
15 <script>
16 stork.register(
17 'federalist',
18 'https://files.stork-search.net/federalist.st'
19 )
20 </script>
21 </body>
22</html>

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/stork.js"></script>
<script>
stork.register(
'federalist',
'https://files.stork-search.net/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/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:

config.toml
1[input]
2base_directory = "federalist"
3url_prefix = "https://www.gutenberg.org/files/1404/1404-h/1404-h.htm#link2H_4_"
4files = [
5 {path = "federalist-1.txt", url = "0001", title = "General Introduction"},
6 {path = "federalist-2.txt", url = "0002", title = "Concerning Dangers from Foreign Force and Influence"},
7 {path = "federalist-3.txt", url = "0003", title = "Concerning Dangers from Foreign Force and Influence 2"},
8 {path = "federalist-4.txt", url = "0004", title = "Concerning Dangers from Foreign Force and Influence 3"},
9]

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.

© 2019–2021

Stork is built and shepherded by James Little, who's really excited that you're checking it out. If you have any questions or comments, feel free to tweet at him or open an issue on Github.

This site is open source. Please file a bug or open a PR if you see something confusing or incorrect. PRs are always welcome!

Logo by Bruno Monts. Please contact James Little before using the Stork logo. Thanks to Bruno and the fission.codes team for making this logo happen.