Stork is in beta. Please adjust your expectations accordingly. See the roadmap for more information.
Home Documentation Changelog Roadmap

Stork

Impossibly fast web search, made for static sites.

By James Little.

Search through the Federalist Papers (except just the first twenty):

Stork is two things that work in tandem to put a beautiful, fast, and accurate search interface on your static site. First, it’s a program that indexes your content and writes that index to disk. Second, it’s a Javascript library that downloads that index, hooks into a search input, and 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 built with content creators in mind, in that it requires little-to-no code to get started and can be extended deeply. It’s perfect for JAMstack sites and personal blogs, but can be used wherever you need a search interface.

Latest version: 0.5.3

Latest index protocol: stork-2

Javascript library last updated: 2020-03-28

Check out the latest release on Github

Getting Started

To begin, let's first embed the Federalist Paper search box in the demo above in a web page. Once that's working, we'll generate a new index with custom content and feed that into the search box.

Step 1: Include the HTML

The demo above uses some custom CSS, but can generally be recreated with the following HTML:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Federalist Search</title>
    <link rel="stylesheet" href="https://files.stork-search.net/basic.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/stork.js"></script>
    <script>
      stork.register(
        'federalist',
        'https://files.stork-search.net/federalist.st'
      )
    </script>
  </body>
</html>

Putting that code in a new HTML page will get you a copy of the demo.

!

Note:

Stork is a fully hosted library, and can't be downloaded from NPM yet. Your script tag should point to the full url (served behind a Cloudfront CDN): https://files.stork-search.net/stork.js. This also means that the hosted script registers the global variable stork, which can cause conflicts if you're trying to use that variable name for something else.

Stork hooks into existing HTML that you include on your page. Each Stork instance has to have an input element and an output element, and generally Stork themes will ask you to put the input and output in a wrapper element.

The input must be an <input data-stork="federalist"> element. The must be an empty <div data-stork="federalist-output"></div> element.

Here, federalist is the name with which you register that search instance. (By registering a search instance under a certain name, you can have multiple, independent search boxes on a page, all pointing to different indices.) It doesn't have to be federalist -- you can change it to whatever you want.

Step 2: Include the Javascript

You need to include stork.js by embedding the following script in your HTML, right above the closing </body> tag:

<script src="https://files.stork-search.net/stork.js"></script>

This will load the Stork WebAssembly blob and create the Stork object, which will allow for registering and configuring indices.

After this script tag, you should register a search instance by associating a downloadable index to a name, which should match up with the data-stork elements elsewhere on the page.

stork.register("federalist", "http://files.stork-search.net/federalist.st");

Earlier, I generated a search index for the contents of the first twenty Federalist Papers and uploaded it to the above URL. Including the above code will download that index when your web page loads and hook it into the federalist input and output elements.

After you include the boilerplate HTML and register the search index, your search field should have the same functionality as the one above, though it might be a bit uglier. You can include the basic theme CSS to make it slightly nicer. Put this before your </head> tag, if you haven't already:

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

Play around with the search field you created. Try to type in multiple words. Search for a typo and see what happens. Once you get bored, keep reading: we'll generate a new index so you can search through your own content.

Generating an Index

You probably don't want to add an interface to your own website that lets you search through the Federalist papers. Here's how to make your search bar yours.

A search index is built from files on your computer. When creating a search index, you create a configuration file that defines a list of documents on disk and includes some metadata about those documents. When you run the Stork command line application, Stork will build its search index based on the contents of those files and the specified metadata.

To begin, you need a configuration file that describes, among other things, that list of files. Configuration files are formatted as TOML files.

[input]
base_directory = "test/federalist"
files = [
    {path = "federalist-1.txt", url = "/federalist-1/", title = "Introduction"},
    {path = "federalist-2.txt", url = "/federalist-2/", title = "Concerning Dangers from Foreign Force and Influence"},
    {path = "federalist-3.txt", url = "/federalist-3/", title = "Concerning Dangers from Foreign Force and Influence 2"},
    {path = "federalist-4.txt", url = "/federalist-4/", title = "Concerning Dangers from Foreign Force and Influence 3"},
    {path = "federalist-5.txt", url = "/federalist-5/", title = "Concerning Dangers from Foreign Force and Influence 4"},
    {path = "federalist-6.txt", url = "/federalist-6/", title = "Concerning Dangers from Dissensions Between the States"},
    {path = "federalist-7.txt", url = "/federalist-7/", title = "Concerning Dangers from Dissensions Between the States 2"},
    {path = "federalist-8.txt", url = "/federalist-8/", title = "The Consequences of Hostilities Between the States"},
    {path = "federalist-9.txt", url = "/federalist-9/", title = "The Union as a Safeguard Against Domestic Faction and Insurrection"},
    {path = "federalist-10.txt", url = "/federalist-10/", title = "The Union as a Safeguard Against Domestic Faction and Insurrection 2"}
]

[output]
filename = "federalist.st"

This TOML file describes the base directory of all your documents, then lists out:

  • The path on disk where that file can be found, in relation to the base directory
  • The URL to where that search result will link
  • The title of the document

To build an index from a TOML configuration file, first install the Stork binary (Homebrew instructions provided for MacOS, but you can also build from source if you want):

$ brew install jameslittle230/stork-tap/stork

Then run the command with the --build flag:

$ stork --build federalist.toml

This will create a new file at federalist.st, as specified by the output.filename value in the configuration file.

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.

You might want to test your generated index from the command line. You can use the same command line tool used to build the index to search through a given index:

$ stork --search federalist.st "liberty"

which will search the index at federalist.st for all entries with the word liberty in them.

Once the index is uploaded, you can change the URL in your Javascript's stork.register() call to point to your index instead of the Federalist Papers index. The search field will no longer search through the Federalist Papers, it will search through the content you indexed instead.

Continue to the docs to learn about configuration and customization.

Next: Review the Docs →