Search Integration

• Introduction
• Requirements
• Enabling search integration
• How indexing works
• Frontend search behavior
• Search results page
• Customizing the search widget
• Limitations and caveats

Note: This functionality is part of Staatic Premium and requires an active subscription. Connect your Staatic account before enabling search.

Introduction

Staatic Search provides a dynamic backend and frontend autocomplete widget for search on a static site. During publication, Staatic indexes selected WordPress content in Staatic Search. Visitors query Staatic Search from the static site instead of using WordPress search.

Use Search Integration when your static site needs visitor-facing search without routing search requests back to WordPress.

Requirements

Search Integration depends on Premium account state and a connected Staatic account.

Enabling search integration

To provide search results to visitors of your static site, Staatic Search needs to index the selected WordPress content.

To enable search integration, follow these steps:

1. Go to the WordPress Admin and click Staatic > Settings > Integration.
2. Make sure Enable search integration with WordPress search functionality is checked.
3. Optionally, limit the Post Types that will be included in the search index.
4. Optionally, adjust Maximum Results to control how many suggestions are shown to visitors. The default is 5.
5. Click Save Changes.

By default, Staatic includes pages and the post types that are public, publicly queryable and shown in navigation menus. Password-protected posts and pages are never indexed. Changing the selected post types marks the search index for reindexing during the next eligible publication.

How indexing works

Search indexing is part of the publication process.

Indexing updates happen during supported static publications, not immediately when a post is saved. Staatic tracks post changes, scheduled posts that become published, and deleted posts so the next publication can update the index.

Preview publications keep preview search results separate from live search results. Publications that skip deployment or are based on another source publication do not run the search indexing tasks.

Staatic indexes post titles and post content by default. Indexed records also include metadata such as post type, excerpt, dates, permalink, author information when available, and thumbnail information when available.

The Force reindexing during next publication setting clears and rebuilds the indexed records during the next eligible publication. Use it after changing post type selection or when search results appear stale.

Frontend search behavior

Staatic initializes the search widget on normal WordPress search inputs and on custom fields marked for Staatic Search.

When a visitor types a query, the widget sends the query to Staatic Search with the configured maximum result count. Selecting a result redirects the visitor to that result’s indexed permalink. Pressing Enter without selecting one opens the search results page, when you have one, from a search field that searches your site: a form that submits to your home page, as WordPress search forms do, or a Staatic search field outside a form. Other forms submit as they normally do. Without a results page, a WordPress search form stays on the page, because on a static site it would only reach the home page.

The frontend Maximum Results setting controls how many suggestions the widget requests. The default is 5.

Search results page

Note: The search results page requires Staatic Premium 1.15.1 or later.

Suggestions take a visitor straight to one page. A search results page lists every match, with page numbers, on a page of your own site. It is optional, and its results load in the visitor’s browser from Staatic Search, like suggestions.

To set it up:

1. Create and publish a WordPress page for the results, for example Search at /search/.
2. Go to Staatic > Settings > Integration and choose that page under Search results page. Optionally, change Results per page (default 10). Click Save Changes.
3. Add the Staatic Search results block to the page, or the [staatic_search_results] shortcode. Both are available once a results page is chosen.
4. Publish your site.

To limit the page to some post types, set Post types in the block settings, or add post_types to the shortcode: [staatic_search_results post_types="article,page"]. Content inside the block, or between the opening and closing shortcode tags, is shown before a search, when nothing matches, and to visitors without JavaScript.

Visitors get a search field with suggestions, an estimated number of results, and each match with its title, a snippet with the search words highlighted, and its featured image. Once a results page is set:

• Search forms that submit to your home page, as WordPress search forms do, submit to the results page instead, with Enter or their search button. Add data-staatic-search-results="false" to a form to leave it as it is.
• Enter in a Staatic search field outside a form, without a suggestion selected, opens the results page.
• Other forms submit as they normally do.
• Old WordPress search links such as /?s=cache are sent to the results page.
• The page is marked noindex and left out of sitemaps and of your own search index.

The page reads the search from its address: q for the query, type for post types and pg for the page of results, for example /search/?q=cache&type=article. To change its HTML, copy premium/partials/search/results.php from the Staatic plugin to staatic/search/results.php in your (child) theme and edit the copy.

Each page of results a visitor opens counts as one search request, like each lookup in a search box.

Customizing the search widget

The search widget included with Staatic Search has been designed to integrate with most sites and themes. It positions autocomplete results relative to the search query field and appends the result list to the page body.

You may want to change the appearance of the widget or the result list so it fits your site better.

CSS styling

The easiest way to change the search widget’s appearance is by adding some CSS styling. The basic HTML structure of the search widget looks like this:

<input name="s" type="search">

<div class="autocomplete-result-list" data-position="above|below">
    <div class="autocomplete-result">
        <a class="suggestion-link">
            <img class="suggestion-thumbnail" alt="">
            <div class="suggestion-attributes">
                <span class="suggestion-title"></span>
                <span class="suggestion-content"></span>
            </div>
        </a>
    </div>
</div>

For a custom field that does not use WordPress’ normal search field name, add data-staatic-search:

<input data-staatic-search name="site-search" type="search">

To keep a normal WordPress search input from being enhanced, add no-autocomplete:

<input class="no-autocomplete" name="s" type="search">

Suggestion template

Each suggestion is rendered with a Handlebars template that receives the search result, so every field of the record is available in it. To change the template, copy premium/partials/search/widget.php from the Staatic plugin to staatic/search/widget.php in your (child) theme and edit the copy. Staatic uses the theme’s copy when it exists. Keep the id="staatic-search-suggestion-template" attribute, and write closing tags inside the template as <\/tag>, like the original does, so they survive publication.

For example, to show a section label that your theme adds as a custom field with the staatic_search_item filter:

<span class="suggestion-title">{{{ _highlight.post_title }}}<\/span>
{{#if custom.label}}
    <span class="suggestion-label">{{ custom.label }}<\/span>
{{/if}}

Use double braces for custom fields: they escape the value. Triple braces are only for the highlighted fields that Staatic Search prepares itself.

Limiting a field to some post types

To have a search field suggest only some post types, add data-staatic-search-post-types with a comma-separated list of post type names. The post types must also be selected under Indexable Post Types, so they are in the search index. Names that are not valid post type names are ignored, and without the attribute (or without any valid name) the field searches all indexed post types.

<input data-staatic-search data-staatic-search-post-types="page" name="s" type="search">

For the theme’s search form, add the attribute with WordPress’ get_search_form filter, for example in your theme’s functions.php (WordPress 6.2 or later). Block themes render the Search block instead; use the render_block_core/search filter with the same function.

add_filter('get_search_form', function ($form) {
    $tags = new WP_HTML_Tag_Processor($form);
    while ($tags->next_tag('input')) {
        if ($tags->get_attribute('name') === 's') {
            $tags->set_attribute('data-staatic-search-post-types', 'post,page');
            break;
        }
    }
    return $tags->get_updated_html();
});

Limitations and caveats

Search Integration is designed for static-site autocomplete and search suggestions. Keep these boundaries in mind:

• Index updates are publication-driven. Saving a post records a change, but visitors see the updated search result after the next eligible publication indexes it.
• Default search matching uses post titles and post content. Searching other fields requires custom development.
• The frontend widget uses the first registered search index.
• Theme search forms that do not use input[name="s"] need data-staatic-search to be enhanced.
• Public search requests are handled by Staatic, not by WordPress login state.
• Search analytics count search queries per index. They do not track result clicks.