davidbgk
/
larlet-fr-david-cache

title: Ajout d’un module de recherche pour Hugo
url: https://lord.re/posts/206-recherche-pour-un-blog-statique/
hash_url: 2f3ed5cb927427fb834b4a9d657592be

<p>Régulièrement j'ai des gens qui ne retrouvent pas un article que j'ai écrit.
Et moi le premier, je cherche souvent pour savoir où j'ai bien pu parler d'un truc.
Et c'est vrai qu'étant donné qu'il y a de plus en plus de contenu sur mon blog, c'est forcément c'est de plus en plus complexe de se rappeler ou de retrouver une page précise.</p>
<p>Étant donné que j'ai déjà ouvert toutes les pages dans mon navigateur, je me base sur l'autocomplétion du navigateur mais c'est loin d'etre parfait.</p>
<p>Jusqu'à présent je recommandai du coup de se rendre sur la <a href="https://lord.re/mono/">monopage</a>.
Cette page contient absolument tout le contenu du site, il suffit donc d'attendre qu'elle charge puis utiliser la fonction recherche du navigateur (<kbd>Ctrl-f</kbd>) mais c'est un usage qui est au final marginal.
Ça fonctionne mais c'est peu plaisant et puis la page est de plus en plus longue à charger vu qu'elle pèse désormais près de 3Mo de HTML (bon une fois gzippé ça tombe à 800Ko).</p>
<p>L'autre technique est tout simplement de chercher via un moteur de recherche conventionnel comme le fameux <strong>DuckDuckGo</strong> ou autre moteur alternatif.
Mon site est pas mal crawlé et donc plutôt bien indexé donc ça fonctionne pas trop mal.
Mais c'est quand même dommage de dépendre de la bonne volonté des moteurs de recherche pour une fonctionnalité que j'aimerai offrir moi-même dans ma quête d'autonomie et d'indépendance.</p>
<h2 id="cahier-des-charges">Cahier des charges</h2>
<p>Donc je voulais un truc adapté à mes contraintes.</p>
<ul>
<li>
<p>La première c'est d'être <strong>statique</strong>, c'est-à-dire que je n'ai rien à installer sur le serveur hébergeant le site.
Pas de PHP, pas de node, pas …</p>
</li>
<li>
<p>La seconde c'est que ce soit du <strong>logiciel Libre</strong> simple à utiliser.
Encore que la simplicité est très négociable si ça fait bien le taf.
Le but étant de ne pas avoir à installer cinquante trucs pour que ça fonctionne.</p>
</li>
<li>
<p>La troisième c'est que pour l'utilisateur ça soit <strong>pratique</strong> donc si c'est plus complexe ou moins performant que de fouiller manuellement la monopage ça sert à rien.</p>
</li>
</ul>
<h2 id="solution-sélectionnée">Solution sélectionnée</h2>
<p>Il y a trois semaines, lors de ma navigation habituelle sur Hacker News je tombe sur un ptit projet qui semble fait pour me titiller : <strong><a href="https://github.com/tinysearch/tinysearch">Tinysearch</a></strong></p>
<p><em>C'est codé en rust, nécessite un bout de javascript + un bout de webassembly et c'est tout.</em>
Il est prévu pour être mis en place dans mon cas d'usage (les sites statiques) donc je n'aurai pas besoin de tordre un outil pour transformer une pince coupante en pince croco…</p>
<p>Après je n'ai pas cherché plus, je suis tombé par hasard sur ça et ça matchait vraiment bien.
Si ça se trouve il existe mieux ailleurs mais pour le moment je saurai m'en contenter.</p>
<h2 id="donc-la-marche-à-suivre-">Donc la marche à suivre ?</h2>
<p>Alors d'un point de vue utilisateur c'est simplement un petit bout de javascript, qui va lancer un bout de webassembly qui contient le moteur de recherche + son index.</p>
<p>Il faut donc au préalable (après la génération du site) créer (tout du moins le remettre à jour) cet index.</p>
<p>Il faut également intégrer dans les pages (ou dans une seule comme j'ai préféré) ajouter un peu de html+js pour charger ça et voilà.
C'est donc vraiment pas intrusif pour le site.</p>
<h2 id="création-de-lindex">Création de l'index</h2>
<p>Alors ce cher <strong>Tinysearch</strong> a besoin d'un index mais ce n'est pas lui qui va le créer.
Enfin il va se créer son index à lui en touillant tout à sa sauce mais il faut lui fournir les données brutes.</p>
<p>Ici, les données brutes, c'est un fichier json contenant la liste de tous les articles.
Pour chaque article il veut un <strong>titre</strong>, une <strong>url</strong> et le <strong>contenu</strong>.</p>
<p>Il faut donc demander à notre cher <strong>Hugo</strong> de nous générer un fichier json avec la bonne syntaxe.
Bon alors sur le <a href="https://github.com/tinysearch/tinysearch">github de Tinysearch</a> on trouve un peu de doc dont une toute fraîche détaillant la marche à suivre pour Hugo mais je l'ai quelque peu modifiée (<del>je la proposerai ptet en retour si j'ai pas de mauvais retours</del> c'est fait).</p>
<p>On va donc devoir créer 1 fichier définissant la structure du fichier.</p>
<details><summary>layout/_default/list.json.json (oui oui, deux fois .json)</summary>
<div class="highlight"><pre tabindex="0"><code class="language-golang" data-lang="golang"><span><span>[
</span></span><span><span>{{ <span>range</span> <span>$</span><span>index</span> , <span>$</span><span>e</span> <span>:=</span> .<span>Site</span>.<span>RegularPages</span> }}{{ <span>if</span> <span>$</span><span>index</span> }}, {{<span>end</span>}}{{ <span>dict</span> <span>"title"</span> .<span>Title</span> <span>"url"</span> .<span>Permalink</span> <span>"body"</span> .<span>Plain</span> | <span>jsonify</span> }}{{<span>end</span>}}
</span></span><span><span>]</span></span></code></pre></div>
</details>
<p>Il faut maintenant dire à Hugo de générer ce fichier pour la home uniquement, on a pas besoin de générer un json pour chacune des pages/liste.</p>
<p>Il faut donc éditer la config globale :</p>
<details><summary>extrait du config.toml</summary>
<div class="highlight"><pre tabindex="0"><code class="language-toml" data-lang="toml"><span><span>[<span>outputs</span>]
</span></span><span><span>  <span>home</span> = [<span>"html"</span>,<span>"rss"</span>,<span>"json"</span>]</span></span></code></pre></div>
</details>
<p>Donc là, pour la home, il générera le html habituel, le rss associé mais également le json.</p>
<p>Voilà maintenant à la racine de votre site ouaib vous trouverez votre fichier index.json</p>
<details><summary>extrait du index.json généré</summary>
<div class="highlight"><pre tabindex="0"><code class="language-json" data-lang="json"><span><span>[
</span></span><span><span>    {
</span></span><span><span>        <span>"body"</span>: <span>"blabla"</span>,
</span></span><span><span>        <span>"title"</span>: <span>"Recherche"</span>,
</span></span><span><span>        <span>"url"</span>: <span>"https://lord.re/recherche/"</span>
</span></span><span><span>    },
</span></span><span><span>    {
</span></span><span><span>        <span>"body"</span>: <span>"encore du blabla"</span>,
</span></span><span><span>        <span>"title"</span>: <span>"Event Horizon"</span>,
</span></span><span><span>        <span>"url"</span>: <span>"https://lord.re/visionnages/event-horizon/"</span>
</span></span><span><span>    }
</span></span><span><span>]</span></span></code></pre></div>
</details>
<p>Voilà pour la partie création d'index.
Vous remarquerez que ce fichier json peut vite être assez gros.
Dans mon cas, il pèse 1.9Mo (710Ko gzippé) à comparer à la monopage qui fait 2.9Mo (835Ko gzippée).</p>
<h2 id="utilisation-de-tinysearch">Utilisation de Tinysearch</h2>
<p>Bon je zappe la partie installation : c'est un logiciel très jeune en rust qui n'est probablement dans aucune distribution linux pour le moment.
Je l'ai direct git cloné depuis github et j'ai même touillé une variable dans le code pour le faire fonctionner mais ça devrait être amélioré très bientôt cette partie-là.</p>
<p>Bref, la seule chose à faire est de lui donner à manger votre <em>index.json</em>.
Mettez-vous dans un dossier vierge créé pour l'occasion car il va pondre quelques fichiers.</p>
<p><kbd>tinysearch /tmp/www/public/fr/index.json</kbd>.
Et là ça va voltiger dans tous les sens.
Pour le moment, à chaque fois que vous l'invoquerez il va récupérer des paquets rust, compiler quelques morceaux, lire votre index compiler un binaire en rust, le transpiler en webassembly et vous générer donc un fichier <em>js</em>, un <em>wasm</em> (contenant entre autre l'index dans son format à lui) quelques fichiers en plus qui ne seront pas utiles (sauf peut-être le demo.html pour tester vite fait).</p>
<p>Donc vous pouvez y récupérer le fichier js et wasm et le coller dans votre Hugo où bon vous semble, j'ai choisi de foutre ça dans <em>static/js/</em> alors que bon le fichier wasm en vrai n'est pas statique car il changera à chaque nouvelle génération d'index.</p>
<p>Ces deux fichiers peuvent être gzippés (et c'est très fortement recommandé).
Si votre site est assez conséquent le fichier wasm peut rapidement devenir un peu gros mais il se compresse vraiment très bien.
Pour info, mon fichier <em>tinysearch_engine_bg.wasm</em> pèose 2Mo (mais 330Ko gzippé).</p>
<h2 id="création-dune-page-de-recherche">Création d'une page de recherche</h2>
<p>J'aurai pu foutre la recherche direct dans la sidebar mais ça aurait alourdi toutes les pages du site alors que la recherche ne sera pas utilisée à tous les coups.</p>
<p>J'ai donc créé une page grâce à <kbd>hugo new recherche.md</kbd> et à l'intérieur les trois quarts sont du html.</p>
<details><summary>extrait de content/recherche.md</summary>
<div class="highlight"><pre tabindex="0"><code class="language-html" data-lang="html"><span><span>&lt;<span>section</span> <span>class</span><span>=</span><span>"ideas"</span>&gt;
</span></span><span><span>&lt;<span>article</span>&gt;
</span></span><span><span>Vous êtes tout tristouille en train de chercher une page en particulier dans mon ptit bordel ?
</span></span><span><span>
</span></span><span><span>Allez on va tenter de la trouver ensemble !
</span></span><span><span>
</span></span><span><span> &lt;<span>script</span> <span>type</span><span>=</span><span>"module"</span>&gt;
</span></span><span><span>    <span>import</span> { <span>search</span>, <span>default</span> <span>as</span> <span>init</span> } <span>from</span> <span>'https://lord.re/js/tinysearch_engine.js'</span>;
</span></span><span><span>    window.<span>search</span> <span>=</span> <span>search</span>;
</span></span><span><span>
</span></span><span><span>    <span>async</span> <span>function</span> <span>run</span>() {
</span></span><span><span>      <span>await</span> <span>init</span>(<span>'https://lord.re/js/tinysearch_engine_bg.wasm'</span>);
</span></span><span><span>    }
</span></span><span><span>
</span></span><span><span>    <span>run</span>();
</span></span><span><span>  &lt;/<span>script</span>&gt;
</span></span><span><span>
</span></span><span><span>  &lt;<span>script</span>&gt;
</span></span><span><span>    <span>function</span> <span>doSearch</span>() {
</span></span><span><span>      <span>let</span> <span>value</span> <span>=</span> document.<span>getElementById</span>(<span>"recherche"</span>).<span>value</span>;
</span></span><span><span>      <span>const</span> <span>arr</span> <span>=</span> <span>search</span>(<span>value</span>, <span>21</span>);
</span></span><span><span>      <span>let</span> <span>ul</span> <span>=</span> document.<span>getElementById</span>(<span>"results"</span>);
</span></span><span><span>      <span>ul</span>.<span>innerHTML</span> <span>=</span> <span>""</span>;
</span></span><span><span>
</span></span><span><span>      <span>for</span> (<span>i</span> <span>=</span> <span>0</span>; <span>i</span> <span>&lt;</span> <span>arr</span>.<span>length</span>; <span>i</span><span>++</span>) {
</span></span><span><span>        <span>var</span> <span>li</span> <span>=</span> document.<span>createElement</span>(<span>"li"</span>);
</span></span><span><span>
</span></span><span><span>        <span>let</span> <span>elem</span> <span>=</span> <span>arr</span>[<span>i</span>];
</span></span><span><span>        <span>let</span> <span>elemlink</span> <span>=</span> document.<span>createElement</span>(<span>'a'</span>);
</span></span><span><span>        <span>elemlink</span>.<span>innerHTML</span> <span>=</span> <span>elem</span>[<span>0</span>];
</span></span><span><span>        <span>elemlink</span>.<span>setAttribute</span>(<span>'href'</span>, <span>elem</span>[<span>1</span>]);
</span></span><span><span>        <span>li</span>.<span>appendChild</span>(<span>elemlink</span>);
</span></span><span><span>
</span></span><span><span>        <span>ul</span>.<span>appendChild</span>(<span>li</span>);
</span></span><span><span>      }
</span></span><span><span>    }
</span></span><span><span>  &lt;/<span>script</span>&gt;
</span></span><span><span>
</span></span><span><span>  &lt;<span>input</span> <span>type</span><span>=</span><span>"text"</span> <span>id</span><span>=</span><span>"recherche"</span> <span>onkeyup</span><span>=</span><span>"doSearch()"</span> <span>style</span><span>=</span><span>"margin:1em;padding:1em;font-size:2rem;background-color:#222;color:#ddd;border-radius:0.3em;border:none;width:90%;box-shadow:inset 0 0 1em #111;"</span> <span>placeholder</span><span>=</span><span>"recherche"</span>&gt;
</span></span><span><span>  &lt;<span>ul</span> <span>id</span><span>=</span><span>"results"</span>&gt;
</span></span><span><span>  &lt;/<span>ul</span>&gt;</span></span></code></pre></div>
</details>
<p>Donc on voit qu'il y a le js et le wasm qui sont chargés (faudra que vous adaptiez les url), j'ai un chouilla stylisé la boite d'input et voilà.</p>
<h2 id="profit-">Profit !</h2>
<p>Normailement c'est tout bon.</p>
<p>Enfin normalement si vous avez pas joué les ptits malins avec des <abbr title="Content Security Policy">CSP</abbr>.
Visiblement le webassembly (wasm) nécessite d'avoir <kbd>script-src 'unsafe-eval'</kbd> pour accepter de tourner sinon vous aurez une erreur étrange dans la console.</p>

<p>En gros <strong>Tinysearch</strong> se base sur votre index exhaustif et utilise un <em>bloom filter</em> (j'y connais rien dans ce domaine) ce qui lui permet d'avoir une corresponsdance entre un mot et du contenu.
L'avantage c'est que potentiellement ce nouvel index peut-être vraiment petit par rapport à la taille de données indexées.
L'inconvénient c'est que c'est assez approximatif, certains termes peuvent donner des résultats faux-positifs et aussi quelques faux-négatifs (mais plus rare).</p>
<p>Vu que cet index est transféré au navigateur web et que c'est également le navigateur qui doit s'en dépatouiller lors d'une recherche, on ne peut pas se permettre d'avoir un fichier trop lourdingue.
Du coup c'est un compromis à trouver, pour l'instant c'est pas configurable (tout du moins il faut changer le code et recompiler <strong>Tinysearch</strong>) et c'est fourni avec une valeur ridiculement petite (tout du moins pour le contenu que j'ai).</p>
<p>J'ai passé le <em><abbr title="une valeur qui se trouve dans bin/src/storage.rs à la ligne 68">magic number</abbr></em> de 10 par défaut à 1024.
Le fichier wasm généré est désormais de 2Mo cependant il se gzip à environ 350Ko ce qui est de suite bien plus raisonnable.</p>
<p>Si vous voulez des explications plus en détails sur l'aspect technique de Tinysearch, un ptit tour sur <a href="https://endler.dev/2019/tinysearch/">le blog du créateur du soft</a> où il explique un peu tout.
C'est intéressant mais très technique et en anglais.</p>
<h2 id="pensées-concernant-tinysearch">Pensées concernant Tinysearch</h2>
<p>Le logiciel est <em>vraiment jeune pour le moment</em> et s'oriente d'ailleurs vers une première sortie en version 1.
Du coup ça implique que le code bouge pas mal et que les devs sont vraiment très à l'écoute et réactif.</p>
<p>Il est très probable que son fonctionnement change dans les semaines à venir.
Pour l'instant, on a dépassé le stade du prototype mais on est loin d'un logiciel fini et mature.
Ils sont conscients que le fonctionnement actuel n'est pas optimal.</p>
<p>Il faut pour l'instant modifier le code à la main et recompiler le soft afin de gérer le compromis d'efficacité/poids de l'index.</p>
<p>Ils savent que télécharger et compiler tout un tas de truc lors de son utilisation est pas user-friendly, pas optimisé du tout.
Bref, ce que je raconte aujourd'hui ne sera ptet plus du tout d'actualité d'ici quelque temps.</p>
<h2 id="mettre-à-jour-lindex">Mettre à jour l'index</h2>
<p>Bon maintenant ça veut dire qu'à chaque fois que je rajoute du nouveau contenu je dois désormais recréer l'index.
Ça mériterait d'être placé dans le hook git qui m'automatise la publication du blog, cela dit le logiciel bougeant encore pas mal, je ne vais pas l'optimiser tout de suite.</p>
<h2 id="à-vous-cognacq-jay--à-vous-les-studios-">À vous Cognacq Jay ! À vous les studios !</h2>