Download
Tutorials Github

The Static Search Plugin

The Static Search plugin provides the smoothest, fastest and easiest search possible on your Publii site. Based on the FlexSearch search library, Static Search provides instant, dynamic results for any search terms, and comes equipped with a wealth of options and settings to fine-tune the functionality to perfectly meet the needs of your site visitors.

Enabling the Search section

All official Publii themes have a search area built-into the theme, which will need to be enabled before the plugin will be able to function. To enable the search section:

  1. In the Publii main menu in the left-sidebar, click on the Theme option to open the settings screen.
  2. In the second section of this screen, Custom settings, click on the Search tab in the list of options under the custom settings title to open the search options.
  3. Click on the switcher button next to the Search option to enable the search bar.
  4. The area is now enabled in your theme, and you can move on to enabling and configuring the Static Search plugin.

Adding Static Search plugin support to your theme (for older or custom themes)

To display a search box on your site, simply add the following code snippet where you want it to appear. This will output a search input filed and button that visitors can use to search your site for whatever they're looking for.

{{{@customSearchInput}}}

We also need to modify the config.json file (only if your theme does not support the search plugins) by updating the 'renderer' and  'supportedFeatures' sections with the following flags:

"renderer": {    
     "createSearchPage": true,
     "createContentStructure": true
 },
 "supportedFeatures": {
     "searchPage": true,
     "customSearch": true
 },

Enabling the plugin

To activate the plugin, open the Tools & Plugins section of the Publii app via the left-menu to see a list of installed plugins. Click on the switcher button in the bottom-left of the Static Search tile in this list to enable the plugin.

Once both the plugin and search area in the theme have been enabled the search function will be ready to use on your site, but since Static Search includes a number of settings to fine-tune the search functionality, it's a good idea to open the plugin settings and ensure that everything is configured to suit your needs.

To open the plugin settings, click on the Static Search tile once again, anywhere except on the switcher button, and the settings screen will open. Note that this screen will not be available if the plugin is not enabled first.

Static Search options

The Static Search plugin boasts several options that allow users to specify exactly how the search feature should work on their site; if preferred, the default options will provide a smooth search experience, so modifying these settings is entirely optional. The available settings are as follows:

Search configuration

  • Open a search popup when clicking search input - When this option is enabled, when the visitor clicks on the search input, the search popup will be opened immediately, which usually will only be displayed once a search is run.
  • Open a search popup by CSS selector - When this option is enabled, when the visitor clicks on the any element e.g. glass icon or a link, the search popup will be opened immediately. This option requires a CSS selector provided in the CSS selector field.
  • CSS selector - Add any valid CSS selector here to target an HTML element, so the search popup will display when you click on that element. For example, if you want a popup to display when you click on a button, add a CSS class called for example  'search-popup' to that button e.g. <button class="search-popup"> Open search popup </button>.
  • Submit button - If this option is enabled, a submit button will be displayed in the search box; visitors may click this button to initiate the search, or hit 'Enter' as normal.
  • Minimum character count to trigger search - This option sets the minimum number of characters that must be entered in the search input before results are displayed.
  • Maximum number of search results - Sets the maximum number of search results that can be displayed at once when a search is run, with the most relevant listed first.
  • Show description in results as - Choose whether to display additional information with each item listed in the search results; the available options are:
    • None - The results will display only the post/page title, without any additional information.
    • Excerpt - The results will display an excerpt from the article content; the length of the excerpt depends on the Excerpt length setting in the Theme Settings > Basic settings section of the Publii app, or wherever the read-more is in an article if using a custom excerpt.
    • Meta Description - The results will display a description taken from the posts' meta descriptions.
  • Search input placeholder - Text entered in this field will be displayed as a placeholder in the search input.
  • Search button label - Text entered in this field will be displayed as the name of the button search.
  • Popup search input placeholder - Text entered in this field will be displayed by default in the popup search input when it is opened.
  • Search empty state - Text entered in this field will be displayed in the results area of the screen when no characters have been entered in the search input by the visitor.
  • Text displayed when phrase is too short - The text in this field will be displayed when the visitor has not entered the required number of characters for the search, as defined in the Minimum character count option.
  • No results state - The text in this field will be displayed in the results area when a search has been run, but there are no matching results for the entered search term.
  • Close button - Sets the text for the button that closes the search popup (visible on the mobile view only)

Index configuration

The index configuration section contains the most important options for the Static Search plugin. The various settings in this section tell the plugin which content on your site should be indexed; that is, which parts of your site content such as titles, excerpts, headings etc... should be collected and stored by the plugin so that it can be searched for by your site visitors.

Note: Most users can leave all the options in this section enabled to allow a broader, more accurate search for their site visitors. However, if the indexed site has a large number of posts the index file that is created can be relatively large; in such cases it may be helpful to limit indexing to specific elements to reduce the overall weight of the file. Also, make sure GZIP/Brotli is activated on your server; this will reduce the size of the search index.

The options in this section are:

  • Enable Posts indexing - If enabled, the selected post elements such as the post title, excerpt, headings will be indexed for searching.
  • Exclude hidden posts - If enabled, posts marked as hidden will not be indexed by the search plugin, nor shown in search results.
  • Post title - If enabled, post titles will be indexed and used in searches.
  • Excerpt - If enabled, excerpts from posts will be indexed and used in searches. The amount of content that is indexed depends on the Excerpt length setting in the Site Settings > Basic settings section of the Publii app, or where the read more has been added if using a custom excerpt.
  • Headings (H1-H6) - If enabled, headings within your post content will be indexed and used in searches.
  • Author name - If enabled, the author name in posts will be indexed and used in searches; helpful if you want to allow visitors to search by author name without going to the author-specific page.
  • Meta description - If enabled, the meta description content of each post will be indexed and used in searches.

  • Enable Tags indexing - If enabled, the selected tag elements, such as the tag name, description will be indexed for searching.
  • Exclude hidden tags - If enabled, tags that are set to hidden will not be indexed or displayed in search results.
  • Tag name - If enabled, the tag title will be indexed and used in searches.
  • Tag description - If enabled, each tag's description text will be indexed and used in searches.
  • Meta description - If enabled, the meta description for each tag page will be indexed and used for searches.

  • Enable Post Config indexing: If enabled, you can index selected Post Config options. 
  • Fields to index: Specify the Post Config field names to index, separated by commas.

Advanced options

  • Tokenise option value - This options sets the behavior for the search process; that is, how it looks for the words that are being searched for and how effective the search is. Generally-speaking, the Full setting will provide the most effective search experience, but alternative, simpler options may be used on large websites to limit the amount of memory required for the search. The available settings for this option are:
    • Strict - Only exact matches for the search term will be shown in the results.
    • Forward - Words are searched for starting from the first letter in a forward order, allowing partial matches to be displayed; unfinished words or words with misspellings at the end will still display results e.g. if searching for 'Testing', entering only 'Tes' will provide some results.
    • Reverse - A result will be shown when the letters of the search term occur in both forward or reverse order, provide even more support for misspellings or incomplete searches e.g. if searching for 'Testing', entering either 'Tes' or 'ing' will provide some results.
    • Full - Combines all of the above, plus partial matches for the middle section of the search term e.g. if searching for 'Testing', entering either 'Tes', 'ing' or 'sti', or other combinations thereof will provide some results.
  • Charset - Sets the character set that the Static Search plugin should use in searches. By default this option will safely cover all European languages that use the Latin alphabet, including additional characters for languages with accented letters.
  • Language - Sets the language that the searches will use when recognising similar words coming from the same base word e.g. conjugations of a verb. Uses the ISO-3166 naming convention for languages. Note that not all languages are supported.
  • Enable cache - If enabled, the Static Search plugin will use the available cache to store popular searches in order to provide autocomplete and instant search when typing in the search bar. The options available in this section are:
    • Disabled - No searches will be stored; searches may run slower than when the cache is enabled.
    • Enabled - no size limit - Searches will be saved to provide dynamic searches when typing and autocomplete suggestions if enabled.
    • Enabled - with size limit - Searches will be saved up to a specific limit; after which, only the most popular searches will be stored to provide dynamic search and suggestions.
  • Cache size - This option is only available when the Enable cache option is set to Enabled - with size limit. The number entered in this field defines the maximum number of searches that the plugin should save for dynamic searches and suggestions. By default, this is set to 100.
  • Enable suggestions - If enabled, the search will offer autocomplete suggestions to visitors as they type in the search bar, based on popular searches that have been run previously.
  • Relative URLs - domain - Sets the domain that the search will use to create proper links in the search index.

    Note: Use this option only when you are using relative URLs in the server settings.

Customizing the Static Search plugin's appearance

Advanced users or theme developers may wish to modify the look and feel of the plugin's search box and popup search page; the information in this section will help you to begin customizing the search to fit your theme's aesthetics.

What code generates the Static Search box?

When enabled, the Static Search plugin generates an 'input box', which is a form with the input area where visitors can enter their search term, and a button to submit the search. This form is added to the frontpage in the theme. The code that is generated for this input box is as follows:

it will generate the following output:

<form action="#search" class="search__form">
   <input class="search__input" type="search" placeholder="Search" aria-label="Search"> 
   <button type="submit" class="search__button">
      <span>Search</span>
   </button>
</form>

This code may be useful should you wish to style the search box to your theme.

Modifying the search results appearance

The results from a given search are displayed in a modal pop-up; by using the Custom CSS tool that can be found in the Tools & Plugins section of the Publii main menu, users may modify the look and feel of the results pop-up as per their needs.

Available CSS variables

Below you will find a list of the available CSS variables that are used to style the results popup; you may copy the entire block of code to your Custom CSS tool and make modifications, or make changes only to specific CSS variables from the list.

:root {    
    --pss-width: 672px; 
    --pss-popup-min-height: 210px; 
    --pss-popup-max-height: 576px; 
    --pss-popup-input-height: 70px; 
    --pss-border-radius: 4px; 
    --pss-spacing: 20px; 
    --pss-font-base-size: 15px; 
    --pss-font-family: inherit; 
    --pss-results-title-font-weight: 500; 
    --pss-results-excerpt-line-height: 1.2; 
    
    --pss-bg: #fff; 
    --pss-overlay: rgba(184, 186, 193, 0.9); 
    --pss-border-color: #e7e8ea; 
    --pss-color: #0079f2; 
    --pss-msg-text-color: #6A7082; 
    --pss-input-bg: #fff; 
    --pss-input-text-color: #32353e; 
    --pss-input-placeholder-color: #7f8596; 
    --pss-button-close-bg: #6A7082; 
    --pss-button-close-color: #fff; 
    --pss-results-title-color: #32353e; 
    --pss-results-title-color-hover: #fff; 
    --pss-results-excerpt-color: #6A7082; 
    --pss-results-excerpt-color-hover: #fff; 
    --pss-results-icon-color: #969faf; 
    --pss-results-icon-color-hover: #fff; 
    --pss-results-highlight-bg: #0079f2; 
  } 
    
  @media (prefers-color-scheme: dark) { 
    :root { 
      --pss-bg: #191a1f; 
      --pss-overlay: rgba(10, 10, 12, 0.8); 
      --pss-border-color: #2A2B34; 
      --pss-color: #1089ff; 
      --pss-msg-text-color: #7f8596; 
      --pss-input-bg: #191a1f; 
      --pss-input-text-color: #d9d9e0; 
      --pss-input-placeholder-color: #7f8596; 
      --pss-button-close-bg: #393A47; 
      --pss-button-close-color: #fff; 
      --pss-results-title-color: #d9d9e0; 
      --pss-results-title-color-hover: #fff; 
      --pss-results-excerpt-color: #8c8ea3; 
      --pss-results-excerpt-color-hover: #fff; 
      --pss-results-icon-color: #7f8596; 
      --pss-results-icon-color-hover: #fff; 
      --pss-results-highlight-bg: #1089ff; 
    } 
  }

What are you waiting for?

Start building your site today.

  1. 1 Download Publii
  2. 2 Write your content
  3. 3 Publish your site
Create website