La recherche se configure dans la section flexsearch de la configuration du site.

Sections indexées

Les sections indexées sont listées sous flexsearch.sections, dans l’ordre des groupes de résultats. Par défaut, toutes les sections racines du site sont indexées.

Limite

L’option limit définit le nombre maximum de résultats affichés dans un groupe.

Découpage des pages

Par défaut, chaque page est découpée en un enregistrement par titre <h2> et <h3>, lié à son ancre. Utilisez split: false pour indexer un seul enregistrement par page, comme pour les articles de blog.

Date

Utilisez date: true pour afficher la date de la page dans les résultats, à la place du fil d’Ariane.

Options de recherche

L’option tokenize définit la correspondance des mots (strict, forward, reverse ou full), et encoder la normalisation des caractères, par exemple pour ignorer les accents.

Poids des champs

Chaque champ indexé (titre, page, description et contenu) a une résolution, de 1 à 9 : plus elle est élevée, plus une correspondance dans ce champ est pertinente.

Recherche approchée

Avec suggest: true, la recherche se rabat sur une correspondance approchée quand rien ne correspond strictement : une faute de frappe donne quand même des résultats.

Recherches récentes

Les derniers résultats sélectionnés sont mémorisés dans le navigateur (localStorage, une liste par langue) et affichés dans un groupe « Récents » à l’ouverture de la boîte de recherche. L’option recent définit leur nombre maximum (5 par défaut), ou les désactive avec 0.

Le thème composant FlexSearch ajoute une recherche plein texte côté client à un site Cecil : l’index de recherche est généré lors du build, et interrogé dans le navigateur grâce à la bibliothèque FlexSearch. Pas de serveur, pas de service externe.

Installation

Installez le thème avec Composer :

composer require cecil/theme-flexsearch

Ou téléchargez la dernière archive et décompressez son contenu dans le répertoire themes/flexsearch.

Activer le thème

Ajoutez flexsearch dans la section theme de la configuration :

theme:
  - flexsearch

Ajouter le champ de recherche

Ajoutez la feuille de style dans le <head> du gabarit principal, puis incluez le champ de recherche à l’endroit où le bouton doit apparaître, par exemple dans l’en-tête :

{{ html(asset('flexsearch/flexsearch.css')) }}
{{ include('partials/flexsearch.html.twig') }}

Déclencheur personnalisé

Tout élément portant l’attribut data-flexsearch-open ouvre la fenêtre de recherche, par exemple un lien du menu de navigation.

Les couleurs et dimensions du champ de recherche sont définies par des propriétés personnalisées CSS, avec des valeurs par défaut claires et sombres.

Mode sombre

Le mode sombre suit la préférence du système, sauf si l’élément racine porte un attribut data-theme, comme le fait le sélecteur de thème de cette démo : essayez-le avec le bouton à côté du champ de recherche.

Propriétés personnalisées

Surchargez les propriétés personnalisées dans votre propre feuille de style, par exemple pour utiliser la couleur d’accent de votre site :

:root {
  --flexsearch-accent: #163c56;
  --flexsearch-selected-bg: #f2d07f;
}

Tous les éléments ont une classe flexsearch-* : les styles peuvent aussi être entièrement remplacés.

Le champ de recherche est traduit en anglais et en français, et un index est généré pour chaque langue du site : passez en anglais avec le lien du pied de page, la recherche ne renvoie alors que les pages anglaises.

Ajouter une langue

Extrayez les chaînes à traduire dans une autre langue avec la commande suivante, puis traduisez le fichier généré :

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

Le thème a désormais sa démo en ligne : ce site, construit avec Cecil et déployé sur GitHub Pages à chaque modification du thème. Essayez le champ de recherche ci-dessus !

Les résultats de recherche sont désormais groupés par section : les pages de documentation et les articles de blog ne se disputent plus les premières places. Chaque groupe a sa propre limite, et les articles peuvent afficher leur date à la place du fil d’Ariane.

Nous avons le plaisir d’annoncer la première version du thème composant FlexSearch pour Cecil. Il apporte une recherche plein texte côté client à n’importe quel site Cecil, avec une fenêtre pilotable au clavier inspirée de DocSearch.

Au programme

L’index est un fichier JSON statique généré lors du build, et la bibliothèque FlexSearch n’est chargée qu’à la première recherche.