Stork

Impossibly fast web search, made for static sites.

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. Second, it's a Javascript library that uses that 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 an interactive search bar.

Latest version:

v1.6.0

Released on 2023-01-12

View on Github →

Quickstart

It takes less than five minutes to build the demo at the top of the page.

First, we'll build the search index, scraping the text of the Federalist Papers from the web. Second, we'll embed the Stork UI on our webpage and use the Stork JS library to make it interactive.

Step 1: Create a search index

A Stork search index begins with a configuration file defining where to find the content that can be indexed. Stork can index content from the filesystem, from the internet, or embedded directly in the configuration file.

To index the Federalist Papers, we can set up a configuration file that retrieves them from the web:

federalist.toml

[[input.files]]
title = "1: General Introduction"
url = "https://federalist.stork-search.net/1.html"

[[input.files]]
title = "2-5: Concerning Dangers from Foreign Force and Influence"
url = "https://federalist.stork-search.net/2-5.html"

[[input.files]]
title = "6-7: Concerning Dangers from Dissentions Between the States"
url = "https://federalist.stork-search.net/6-7.html"

[[input.files]]
title = "8: The Consequences of Hostilities Between the States"
url = "https://federalist.stork-search.net/8.html"

[[input.files]]
title = "9-10: The Union as a Safeguard Against Domestic Faction and Insurrection"
url = "https://federalist.stork-search.net/9-10.html"

[[input.files]]
title = "11: The Utility of the Union in Respect to Commercial Relations and a Navy"
url = "https://federalist.stork-search.net/11.html"

[[input.files]]
title = "12: The Utility of the Union in Respect to Revenue"
url = "https://federalist.stork-search.net/12.html"

After installing the Stork command-line tool and saving the file, run the following command to build a search index:

$ stork build --input federalist.toml --output federalist.st

Stork wrote a search index file named federalist.st to your filesystem. You can test it out with the same command-line tool by performing a search:

$ stork search --index federalist.st --query "liberty"

Step 2: Embed it on a webpage

To build an interactive, online search interface, you can use the Stork Javascript library to load your search index and attach it to HTML on your webpage.

You'll need to take the output file generated in the previous step and make it accessible on a web server. I've already done that and uploaded the search index to https://files.stork-search.net/releases/latest/federalist.st.

Stork looks for the data-stork attributes on two tags: an <input> tag where your users will type their search query, and a <div> tag where Stork will render the search results. Here, we're setting up our input and output elements with the name "federalist"—we'll use that name later to point the Javascript library at the correct HTML tags.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Search</title>
  </head>
  <body>
    <input data-stork="federalist" />
    <div data-stork="federalist-output"></div>
  </body>
</html>

By default, Stork's output is completely unstyled, letting you customize the output however you want. However, Stork also provides a "base" theme that can be customized using CSS variables. Before we continue, we'll add some classes, structure, and a <link> tag to load up Stork's "base" theme.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Search</title>
    <link
      rel="stylesheet"
      href="https://files.stork-search.net/releases/latest/stork.css"
    />
  </head>
  <body>
    <div class="stork-wrapper">
      <input data-stork="federalist" class="stork-input" />
      <div data-stork="federalist-output" class="stork-output"></div>
    </div>
  </body>
</html>

Finally, we'll load the Stork Javascript library and register our search index:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Search</title>
    <link
      rel="stylesheet"
      href="https://files.stork-search.net/releases/latest/stork.css"
    />
  </head>
  <body>
    <div class="stork-wrapper">
      <input data-stork="federalist" class="stork-input" />
      <div data-stork="federalist-output" class="stork-output"></div>
    </div>

    <script src="https://files.stork-search.net/releases/latest/stork.js"></script>
    <script>
      stork.register(
        "federalist",
        "https://files.stork-search.net/releases/latest/federalist.st"
      );
    </script>
  </body>
</html>