StaticSearch quickstart

(updated )

469 words, 3-minute read

To use StaticSearch, you must build your static site to a local directory, then:

  1. Index all pages to create JavaScript and JSON data files in the same directory. You must re-run the indexing process every time the site changes.
  2. Add search functionality to your site. It’s easiest to do this after indexing the pages for the first time.

Index a site #

You can run StaticSearch without installation using npx. Assuming you built your static site to a sub-directory named ./build/, run StaticSearch using:

terminal

npx staticsearch

This creates a new directory named ./build/search/ containing StaticSearch’s JavaScript code and word index data.

Indexing help #

For help, enter:

terminal

npx staticsearch --help

Indexing a different directory #

If your site is in a different directory, such as ./dist/, use:

terminal

npx staticsearch --builddir ./dist/

StaticSearch code and indexes is created in ./dist/search/.

Omitting HTML pages: robots.txt #

StaticSearch removes pages from the index when they’re disallowed in the robots.txt file in the site’s root. For example, this disallows indexing for any page with /video/ or /docs/ paths:

robots.txt example

User-agent: *
Disallow: /video/

User-agent: staticsearch
Disallow: /docs/

You can ignore robots.txt with:

terminal

npx staticsearch --ignorerobotfile

Omitting HTML pages: <meta> noindex #

StaticSearch removes pages from the index when a noindex value is found in the meta tag:

HTML <head>

<meta name="robots" content="noindex">

or:

HTML <head>

<meta name="staticsearch" content="noindex">

You can override this with:

terminal

npx staticsearch --ignorerobotmeta

Indexing main content #

StaticSearch attempts to locate your page’s main content. It’ll look for an HTML <main> element, but revert to the <body> when necessary. It will then remove content in blocks such as <nav> inside those elements.

If this is not suitable, you can set alternative DOM elements using CSS selectors. For example, index content in #main but exclude all <header>, <footer>, <nav>, and <div class="related"> elements inside it:

terminal

npx staticsearch --dom '#main' --domx 'header,footer,nav,div.related'

Add search functionality to your site #

The easiest way to add search facilities to your site is to use the <static-search> web component. Add the following snippet to any template, perhaps in the HTML <header>:

template excerpt

<script type="module" src="/search/staticsearch-component.js"></script>

<static-search title="press Ctrl+K to search">
  <p>search</p>
</static-search>

You can put any HTML element inside <static-search> to activate search when clicked. The following example uses an icon that links to a search engine when JavaScript fails or is not available:

template excerpt

<static-search title="press Ctrl+K to search">

  <a href="https://duckduckgo.com/?q=search%20site:mysite.com">
    <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 24 24">
      <path d="M10 4a6 6 0 1 0 0 12 6 6 0 0 0 0-12Zm-8 6a8 8 0 1 1 14.3 5l5.4 5.3a1 1 0 0 1-1.4 1.4l-5.4-5.4A8 8 0 0 1 2 10Z"></path>
    </svg>
  </a>

</static-search>

You’ll need to re-build your site after changing its template – which means you should then re-run the indexer to ensure word indexes are up-to-date.