Building a Search Interface

Once you've built an index file and uploaded it somewhere accessible (like a CDN or your web host), you'll need to use the Stork Javascript library to load the index and build an interactive search interface.

Step 1: Include the HTML

The Stork Javascript library hooks into HTML that already exists on your page and transforms it into an interactive element. To begin, add the following HTML to your page:

<input data-stork="foo" />
<div data-stork="foo-output"></div>

Stork requires an input element and an output element to attach to. Both those elements need to be tagged with a registration name, which is foo above (though yours can be whatever you'd like). You'll use the registration name later.

!

Note:

The input element must conform to the selector input[data-stork="foo"].
The output element must conform to the selector [data-stork="foo-output"]. The registration name must start with a letter.

Step 2: Load the Javascript

The Stork Javascript library downloads the index file and uses a WebAssembly binary to parse and search through it. Right before the closing </body> tag, load the Stork Javascript library from the Stork CDN:

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

If you want more control over where you load external scripts from, you can self-host the Stork Javascript and WebAssembly files. For more information, see Self-hosting Stork.

Step 3: Register your index

The Stork Javascript library exposes a single global variable, stork. After you load the Javascript library, you can add a <script> block where you call the stork.register() function to set Stork up on your web page:

<script>
stork.register("yourIndexName", "https://your-url.com/index-file.st");
</script>

The first argument is an identifier that matches the downloaded index with the DOM elements that will display the search interface. The second argument is the URL where you've uploaded the index file that's been generated by the Stork command line tool. There is a third, optional argument you can pass to the register() function takes: an options object. The options object exposes client-side configuration settings and a callback API; visit the JS API Reference to learn more.

There are also more functions on the Stork object that give you more granular control over the operations that stork.register() performs. To read more about these methods, visit the docs page on Advanced Javascript Usage.

Step 4: Add a theme

Stork is not perscriptive about the CSS you use to style your search index. The Javascript library does not include any pre-defined styling, and you're free to inspect the DOM and add your own styling, if you wish.

Stork also offers pre-built themes, which it exposes through CSS files on the Stork CDN. To include the Basic theme, add the following within your page's <head>:

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

You can see the entire selection of themes in the theme gallery.

Next Steps

© 2019–2022

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.