DocSearch component theme

The DocSearch component theme for Cecil adds Algolia DocSearch to a website: a search button and a search modal, querying an Algolia index of the website.

Demo

Features

• DocSearch button and modal: Ctrl/⌘ + K shortcut, keyboard navigation, recent and favorite searches
• Multilingual: results are filtered on the current language
• Translatable (English and French included)
• Light and dark modes, following the data-theme attribute of the root element

Prerequisites

DocSearch requires an Algolia index of the website: apply to the DocSearch program (free for open source documentation), or run your own crawler.

See Crawler configuration to adapt the crawler to a Cecil website.

Installation

composer require cecil/theme-docsearch

Or download the latest archive and uncompress its contents in themes/docsearch.

Usage

Add docsearch in the theme section of the config.yml, with the Algolia credentials:

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

Important

Use the search-only API key: it is published in the HTML of the pages.

Add the <head> tags (language meta, Algolia preconnect and DocSearch stylesheet) in the main template:

{{ include('partials/docsearch/head.html.twig') }}

Add the search box (button and script) where the button should be displayed, for example in the header:

{{ include('partials/docsearch.html.twig') }}

The button container and the script can also be included separately:

{# in the header #}
{{ include('partials/docsearch/button.html.twig') }}
{# before </body> #}
{{ include('partials/docsearch/script.html.twig') }}

Tip

The partials render nothing until appId, apiKey and indexName are set, so they can be safely included in a theme.

Configuration

Options (default values):

docsearch:
  enabled: true # display the search box (requires `appId`, `apiKey` and `indexName`)
  appId: '' # Algolia application ID
  apiKey: '' # Algolia search API key
  indexName: '' # Algolia index name
  version: '3' # DocSearch version, loaded from jsDelivr
  library: '' # URL of the DocSearch JS library (overrides `version`)
  stylesheet: '' # URL of the DocSearch stylesheet (overrides `version`)
  container: '#docsearch' # CSS selector of the element replaced by the search button
  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 (follows `debug` by default)
  placeholder: '' # placeholder of the search input ("Search docs" by default)
  search_parameters: {} # additional Algolia search parameters

Note

The DocSearch library and stylesheet are downloaded from jsDelivr at build time, and published with the website.

Language

The docsearch:language meta tag is added to every page, so the crawler can store the language of each record in a lang facet. Results are then filtered on the current language (facetFilters: ['lang:<language>']). Set language: false if the index has no lang facet.

Other search parameters can be added (and facetFilters overridden) with search_parameters:

docsearch:
  search_parameters:
    facetFilters: ['lang:en', 'version:2']
    hitsPerPage: 10

Container

The search button replaces the element matching container. To use your own element, set its selector and only include the script:

docsearch:
  container: '#search'

<div id="search"></div>
{{ include('partials/docsearch/script.html.twig') }}

Styles

DocSearch styles are customized with CSS custom properties, for example:

:root {
  --docsearch-primary-color: #1447e6;
}
html[data-theme='dark'] {
  --docsearch-primary-color: #8ec5ff;
}

The dark mode is enabled by a data-theme="dark" attribute on the root element, as set by Cecil's theme selector.

Internationalization

The theme is translated in English and French. Extract the strings to translate in another language with:

cecil util:translations:extract --locale=<locale> --save --theme=docsearch

License

DocSearch component theme is a free software distributed under the terms of the MIT license.

DocSearch © Algolia, released under the MIT license.