Site Search

Statidocs offers two search solutions, each one packaged as a dedicated component theme and displayed as a search button in the header:

Algolia DocSearch: a hosted search service, free for open-source projects;
FlexSearch: a local search index, generated with your site, without any external service.

Both open a search modal with the Ctrl/⌘ + K shortcut, support keyboard navigation, and are translated in English and French.

Algolia DocSearch

The DocSearch component theme queries an Algolia index of your website.

The service is free for any open-source project: apply to the DocSearch program. DocSearch crawls your website periodically and aggregates the content in an Algolia index, which is then queried directly from your front-end using the Algolia API.

DocSearch installation

composer require cecil/theme-docsearch

Then add it after docs in the theme section of the configuration, with your Algolia credentials:

theme:
  - docs
  - docsearch
docsearch:
  appId: <YOUR_APP_ID>
  indexName: <YOUR_INDEX_NAME>
  apiKey: <YOUR_SEARCH_API_KEY>

DocSearch configuration

Main options (default values):

docsearch:
  enabled: true # display the search box
  appId: '' # Algolia application ID
  indexName: '' # Algolia index name
  apiKey: '' # Algolia search API key
  language: true # filter the results on the current language (`lang` facet)
  insights: false # send search events to Algolia Insights
  debug: false # keep the modal open on blur
  placeholder: '' # placeholder of the search input
  search_parameters: {} # additional Algolia search parameters

See the DocSearch component theme documentation for all options.

Crawler configuration

When your website is accepted in the DocSearch program, Algolia creates a default crawler configuration, editable in the Crawler dashboard.

With the Docs theme, the recommended record extractor is:

recordExtractor: ({ helpers }) => {
  return helpers.docsearch({
    recordProps: {
      lvl0: {
        selectors: "#sidebar li>a.active",
        defaultValue: "Documentation",
      },
      lvl1: ["article h1"],
      lvl2: ["article h2"],
      lvl3: ["article h3"],
      lvl4: ["article h4"],
      lvl5: ["article h5"],
      lvl6: ["article h6"],
      content: ["#content p, #content li"],
    },
    aggregateContent: true,
    recordVersion: "v3",
  });
},

Declare lang in the attributesForFaceting of the index settings, to filter results by language:

initialIndexSettings: {
  "<YOUR_INDEX_NAME>": {
    attributesForFaceting: ["type", "lang"],
    // ...
  },
},

See the crawler configuration guide for a complete example.

FlexSearch

As an alternative to DocSearch (no external service, no crawler), the FlexSearch component theme generates a search index at build time (a static JSON file per language), loaded on first use.

FlexSearch installation

composer require cecil/theme-flexsearch

Then add it after docs in the theme section of the configuration:

theme:
  - docs
  - flexsearch

FlexSearch configuration

Results are grouped by section, in the order of flexsearch.sections (every root section is indexed by default):

flexsearch:
  sections:
    docs:
      limit: 5 # maximum number of results in the group

Section options:

Option	Description	Default
`title`	Title of the group of results.	title of the section page
`limit`	Maximum number of results displayed in the group.	`5`
`split`	One record per `<h2>`/`<h3>` heading, or a single record per page.	`true`
`date`	Display the page date in the results.	`false`
`length`	Maximum length of the indexed text of an unsplit page.	`1000`

Other options (default values):

flexsearch:
  enabled: true # display the search box
  trigger: auto # trigger button: auto (icon only on mobile), icon or full
  hotkey: k # Ctrl/⌘ + hotkey opens the search box (false to disable)
  credit: true # display the "Search by FlexSearch" credit
  suggest: true # fall back to fuzzy matching when nothing matches strictly

See the FlexSearch component theme documentation for all options (tokenizer, encoder, fields weight, etc.).