✨ feat: add search functionality (welpo#250)

README.md

@@ -24,6 +24,7 @@ tabi has a perfect score on Google's Lighthouse audit:
 - [X] [Comprehensive multi-language support](https://welpo.github.io/tabi/blog/faq-languages/#how-does-tabi-handle-multilingual-support). Add as many languages as you wish.
 - [X] Support for [comments using giscus, utterances, Hyvor Talk, or Isso](https://welpo.github.io/tabi/blog/comments/).
 - [X] Code syntax highlighting with colours based on [Catppuccin](https://github.com/catppuccin/catppuccin) Frappé.
+- [X] [Local search](https://welpo.github.io/tabi/blog/mastering-tabi-settings/#search) with an accessible, multi-lingual interface.
 - [X] [KaTeX](https://katex.org/) support for mathematical notation.
 - [X] [Stylized and human readable Atom feed](https://welpo.github.io/tabi/atom.xml).
 - [X] [Stylized and human readable sitemap](https://welpo.github.io/tabi/sitemap.xml).

config.toml

@@ -5,6 +5,7 @@ author = "welpo"
 generate_feed = true
 compile_sass = true
 minify_html = true
+build_search_index = true
 
 # To translate the entire theme, there must be a file with the same ISO 639-1
 # (or IETF BCP 47) Code in the `i18n` folder of your site or the tabi theme
@@ -15,6 +16,22 @@ default_language = "en"
 
 taxonomies = [{name = "tags", feed = true}]
 
+[search]
+# Whether to include the title of the page/section in the index.
+include_title = true
+# Whether to include the description of the page/section in the index.
+include_description = true
+# Whether to include the path of the page/section in the index.
+include_path = true
+# Whether to include the rendered content of the page/section in the index.
+include_content = true
+# At which character to truncate the content to. Useful if you have a lot of pages and the index would
+# become too big to load on the site. Defaults to not being set.
+# truncate_content_length = 100
+# Wether to produce the search index as a javascript file or as a JSON file.
+# Accepted value "elasticlunr_javascript" or "elasticlunr_json".
+index_format = "elasticlunr_json"
+
 [markdown]
 highlight_code = true
 highlight_theme = "css"
@@ -30,6 +47,7 @@ generate_feed = true
 compile_sass = true
 minify_html = true
 taxonomies = [{name = "tags", feed = true}]
+build_search_index = true
 
 [languages.ca]
 title = "~/tabi"
@@ -43,6 +61,13 @@ taxonomies = [{name = "tags", feed = true}]
 # Check out the documentation (or the comments below) to learn how to customise tabi:
 # https://welpo.github.io/tabi/blog/mastering-tabi-settings/
 
+# Search index format.
+# For Zola 0.17.X users only.
+# This MUST MATCH the setting in [search].index_format.
+# Example: If [search].index_format is "elasticlunr_javascript", set:
+# index_format = "elasticlunr_javascript"
+# index_format = ""
+
 # Enable JavaScript theme toggler to allow users to switch between dark/light mode.
 # If disabled, your site will only use the theme specified in the `default_theme` variable.
 theme_switcher = true

content/blog/javascript/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Sense JavaScript obligatori"
 date = 2023-01-06
-updated = 2023-10-06
+updated = 2024-01-07
 description = "JavaScript només s'utilitza quan HTML i CSS no són suficients."
 
 [taxonomies]
@@ -16,6 +16,8 @@ Aquest tema no requereix JavaScript obligatori. Opcionalment, pot carregar una q
 
 ## Opcions habilitades globalment
 
+- [**Cerca**](@/blog/mastering-tabi-settings/index.ca.md#cerca). Activada establint un idioma per defecte i `build_search_index = true` a la secció principal de `config.toml`. (~23KB de JavaScript)
+
 - L'**interruptor de mode clar/fosc** es pot habilitar configurant `theme_switcher = true` a la secció `[extra]` del teu `config.toml` (~1KB de JavaScript).
 
 - **Decodificació de correu electrònic** (~400 bytes). Per protegir contra robots de correu brossa, pots configurar `encode_plaintext_email = true`. Si el teu lloc web està en un repositori públic, considera utilitzar el teu `email` com una cadena codificada en base64[^1].

content/blog/javascript/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Sin JavaScript obligatorio"
 date = 2023-01-06
-updated = 2023-10-06
+updated = 2024-01-07
 description = "JavaScript solo se utiliza cuando HTML y CSS no son suficientes."
 
 [taxonomies]
@@ -16,6 +16,8 @@ Este tema no requiere JavaScript de manera obligatoria. Opcionalmente, puede car
 
 ## Opciones habilitadas globalmente
 
+- [**Búsqueda**](@/blog/mastering-tabi-settings/index.es.md#busqueda). Habilitada estableciendo un idioma por defecto y `build_search_index = true` en la sección principal de `config.toml`. (~23KB de JavaScript)
+
 - El **interruptor de modo claro/oscuro** puede habilitarse configurando `theme_switcher = true` en la sección `[extra]` de tu `config.toml` (~1KB de JavaScript).
 
 - **Descodificación de correo electrónico** (~400 bytes). Para proteger contra bots que recopilan correos electrónicos desde tu sitio web, puedes configurar `encode_plaintext_email = true`. Si tu sitio está en un repositorio público, para mayor protección, considera configurar tu `email` como una cadena codificada en base64[^1].

content/blog/javascript/index.md

@@ -1,7 +1,7 @@
 +++
 title = "No mandatory JavaScript"
 date = 2023-01-06
-updated = 2023-10-06
+updated = 2024-01-07
 description = "JavaScript is only used when HTML and CSS aren't enough."
 
 [taxonomies]
@@ -16,6 +16,8 @@ This theme has no mandatory JavaScript. Optionally, it can load a minimal amount
 
 ## Globally enabled settings
 
+- [**Search**](@/blog/mastering-tabi-settings/index.md#search). Enabled by setting a default language and `build_search_index = true` on the main section of `config.toml`. (~23KB of JavaScript)
+
 - The **light/dark mode switch** can be enabled by setting `theme_switcher = true` in the `[extra]` section of your `config.toml` (~1KB of JavaScript).
 
 - **E-mail decoding** (~400 bytes). To protect against spambots scraping your e-mail from your website, you can set `encode_plaintext_email = true`. If your site is on a public repository, for extra protection, consider setting your `email` as a base64-encoded string[^1] directly.

content/blog/mastering-tabi-settings/index.ca.md

@@ -1,7 +1,7 @@
 +++
 title = "Domina la configuració de tabi: guia completa"
 date = 2023-09-18
-updated = 2024-01-05
+updated = 2024-01-07
 description = "Descobreix les múltiples maneres en què pots personalitzar tabi."
 
 [taxonomies]
@@ -34,6 +34,57 @@ Per a les configuracions que segueixen aquesta jerarquia, el valor establert a u
 
 ---
 
+## Cerca
+
+| Pàgina | Secció | `config.toml` | Segueix la jerarquia | Requereix JavaScript |
+|:------:|:------:|:-------------:|:--------------------:|:--------------------:|
+|   ❌   |   ❌   |       ✅      |          ❌          |          ✅          |
+
+tabi permet cerca local accessible i multilingüe amb [Elasticlunr](http://elasticlunr.com/). Per activar-la, necessites:
+
+1. Establir un `default_language` a `config.toml`.
+2. Establir `build_search_index = true`.
+3. Opcionalment, configurar la secció `[search]`.
+
+Per exemple:
+
+```toml
+base_url = "https://example.com"
+default_language = "en"
+build_search_index = true
+
+[search]
+index_format = "elasticlunr_json" # O el menys eficient "elasticlunr_javascript".
+include_title = true
+include_description = true
+include_path = true
+include_content = true
+```
+
+**Nota**: per suport de cerca en Xinès/Japonès, necessites utilitzar una [build personalitzada de Zola](https://github.com/getzola/zola/blob/master/Cargo.toml#L54-L55). Addicionalment, actualment no hi ha suport per a la cerca en català.
+
+### Consideracions per a usuaris de Zola 0.17.X
+
+Zola 0.17.X no proporciona accés a la variable `search.index_format` ([informe del bug](https://github.com/getzola/zola/issues/2165)). En utilitzar tabi, s'assumeix l'ús de l'índex JSON, que és més eficient. No obstant això, a causa d'[un altre bug](https://github.com/getzola/zola/issues/2193) solucionat en 0.18.0, l'índex JSON per a llocs multilingües no es genera correctament.
+
+Els usuaris amb versions de Zola anteriors a 0.18.0 que vulguin utilitzar l'índex JavaScript necessiten establir la variable `index_format` a dos llocs:
+
+```toml
+[search]
+index_format = "elasticlunr_javascript"
+
+[extra]
+index_format = "elasticlunr_javascript"
+```
+
+Això assegura que tabi carregui els arxius correctes. Recomanem actualitzar a Zola 0.18.0 o posterior per a una funcionalitat òptima.
+
+### Detalls d'implementació
+
+Per a detalls tècnics sobre la implementació de la cerca, incloent quan es carrega l'índex, característiques d'accessibilitat i altres detalls, consulta el [Pull Request #250](https://github.com/welpo/tabi/pull/250).
+
+---
+
 ## Suport multilingüe
 
 tabi ofereix suport multilingüe complet per al teu lloc Zola, des de configurar un idioma predeterminat fins a afegir tots els que vulguis. Consulta les [preguntes freqüents sobre idiomes](/ca/blog/faq-languages/) per a més informació.

content/blog/mastering-tabi-settings/index.es.md

@@ -1,7 +1,7 @@
 +++
 title = "Domina la configuración de tabi: guía completa"
 date = 2023-09-18
-updated = 2024-01-05
+updated = 2024-01-07
 description = "Descubre las múltiples maneras en que puedes personalizar tabi."
 
 [taxonomies]
@@ -32,6 +32,59 @@ En todos los casos, las opciones de tabi se establecen en la sección `[extra]`.
 
 Para las configuraciones que siguen esta jerarquía, el valor establecido en una página reemplaza el valor de una sección, que a su vez reemplaza el valor global. En resumen: cuanto más específica sea la configuración, mayor prioridad tendrá, o `página > sección > config.toml`.
 
+---
+
+## Búsqueda
+
+| Página | Sección | `config.toml` | Sigue la jerarquía | Requiere JavaScript |
+|:------:|:-------:|:-------------:|:---------------:|:-------------------:|
+|   ❌   |   ❌    |       ✅       |        ❌       |          ✅          |
+
+tabi soporta búsqueda local accesible y multilingüe con [Elasticlunr](http://elasticlunr.com/). Para activarla, necesitas:
+
+1. Establecer un `default_language` en `config.toml`.
+2. Establecer `build_search_index = true`.
+3. Opcionalmente, configurar la sección `[search]`.
+
+Por ejemplo:
+
+```toml
+base_url = "https://example.com"
+default_language = "en"
+build_search_index = true
+
+[search]
+index_format = "elasticlunr_json" # O el menos eficiente "elasticlunr_javascript".
+include_title = true
+include_description = true
+include_path = true
+include_content = true
+```
+
+**Nota**: para soporte de búsqueda en Chino/Japonés, necesitas usar una [build personalizada de Zola](https://github.com/getzola/zola/blob/master/Cargo.toml#L54-L55).
+
+### Consideraciones para usuarios de Zola 0.17.X
+
+Zola 0.17.X no proporciona acceso a la variable `search.index_format` ([reporte del bug](https://github.com/getzola/zola/issues/2165)). Al usar tabi, se asume el uso del índice JSON, que es más eficiente. Sin embargo, debido a [otro bug](https://github.com/getzola/zola/issues/2193) solucionado en 0.18.0, el índice JSON para sitios multilingües no se genera correctamente.
+
+Los usuarios con versiones de Zola anteriores a 0.18.0 que quieran usar el índice JavaScript necesitan establecer la variable `index_format` en dos lugares:
+
+```toml
+[search]
+index_format = "elasticlunr_javascript"
+
+[extra]
+index_format = "elasticlunr_javascript"
+```
+
+Esto asegura que tabi cargue los archivos correctos. Recomendamos actualizar a Zola 0.18.0 o posterior para una funcionalidad óptima.
+
+### Detalles de implementación
+
+Para detalles técnicos sobre la implementación de la búsqueda en tabi, incluyendo cuándo se carga el índice, características de accesibilidad y otros detalles, consulta el [Pull Request #250](https://github.com/welpo/tabi/pull/250).
+
+---
+
 ## Soporte multilingüe
 
 tabi ofrece soporte multilingüe completo para tu sitio Zola, desde configurar un idioma predeterminado hasta añadir todos los que desees. Consulta la [preguntas frecuentes sobre idiomas](/es/blog/faq-languages/) para más información.

content/blog/mastering-tabi-settings/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Mastering tabi Settings: A Comprehensive Guide"
 date = 2023-09-18
-updated = 2024-01-05
+updated = 2024-01-07
 description = "Discover the many ways you can customise your tabi site."
 
 [taxonomies]
@@ -34,6 +34,57 @@ For settings which follow this hierarchy, the value set on a page overrides the
 
 ---
 
+## Search
+
+| Page | Section | `config.toml` | Follows Hierarchy | Requires JavaScript |
+|:----:|:-------:|:-------------:|:-----------------:|:-------------------:|
+|  ❌  |   ❌    |      ✅       |         ❌        |         ✅          |
+
+tabi supports accessible, local multi-lingual search with [Elasticlunr](http://elasticlunr.com/). To enable it, you need to:
+
+1. Set a `default_language` in `config.toml`.
+2. Set `build_search_index = true`.
+3. Optionally, configure the `[search]`.
+
+Here's an example configuration:
+
+```toml
+base_url = "https://example.com"
+default_language = "en"
+build_search_index = true
+
+[search]
+index_format = "elasticlunr_json" # Or the less efficient "elasticlunr_javascript".
+include_title = true
+include_description = true
+include_path = true
+include_content = true
+```
+
+**Note**: for Chinese/Japanese search support, you need to use a [custom Zola build](https://github.com/getzola/zola/blob/master/Cargo.toml#L54-L55).
+
+### Considerations for Zola 0.17.X Users
+
+Zola 0.17.X doesn't provide access to the `search.index_format` variable ([bug report](https://github.com/getzola/zola/issues/2165)). When using tabi, this variable defaults to the more efficient JSON index. However, due to [another bug](https://github.com/getzola/zola/issues/2193) fixed in 0.18.0, the JSON index for multi-language sites is not generated correctly.
+
+Users with Zola versions prior to 0.18.0 who want to use the JavaScript index need to set the `index_format` variable in two places:
+
+```toml
+[search]
+index_format = "elasticlunr_javascript"
+
+[extra]
+index_format = "elasticlunr_javascript"
+```
+
+This ensures tabi loads the right files. We recommend upgrading to Zola 0.18.0 or later for optimal functionality.
+
+### Implementation Details
+
+For technical details about the search implementation in tabi, including when the index loads, accessibility features, and other specifics, see the [Pull Request #250](https://github.com/welpo/tabi/pull/250).
+
+---
+
 ## Multilingual Support
 
 tabi offers comprehensive multilingual support for your Zola site, from setting a default language to adding as many as you wish. Refer to the [multilingual FAQ](blog/faq-languages/) for more information.

content/projects/tabi/index.ca.md

@@ -24,6 +24,7 @@ social_media_card = "social_cards/ca_projects_tabi.jpg"
 - Puntuació perfecta en Lighthouse (Rendiment, Accessibilitat, Millors Pràctiques i SEO).
 - Ressaltat de sintaxi de codi amb colors basats en [Catppuccin](https://github.com/catppuccin/catppuccin) Frappé.
 - Suport per a [comentaris usant giscus, utterances, Hyvor Talk o Isso](https://welpo.github.io/tabi/ca/blog/comments/).
+- [Cerca local](https://welpo.github.io/tabi/ca/blog/mastering-tabi-settings/#cerca) amb una interfície accessible i multilingüe.
 - Tot el JavaScript es pot [deshabilitar completament](https://welpo.github.io/tabi/ca/blog/javascript/).
 - [Codificació de correu](https://welpo.github.io/tabi/ca/blog/mastering-tabi-settings/#correu-electronic-codificat) per a protecció contra spam.
 - [Mapa del lloc estilitzat i llegible per humans](https://welpo.github.io/tabi/sitemap.xml).

content/projects/tabi/index.es.md

@@ -25,6 +25,7 @@ social_media_card = "social_cards/es_projects_tabi.jpg"
 - Resaltado de sintaxis de código con colores basados en [Catppuccin](https://github.com/catppuccin/catppuccin) Frappé.
 - Soporte para [comentarios usando giscus, utterances, Hyvor Talk o Isso](https://welpo.github.io/tabi/es/blog/comments/).
 - Todo el JavaScript se puede [deshabilitar completamente](https://welpo.github.io/tabi/es/blog/javascript/).
+- [Búsqueda local](https://welpo.github.io/tabi/es/blog/mastering-tabi-settings/#busqueda) con una interfaz accesible y multilingüe.
 - [Codificación de correo](https://welpo.github.io/tabi/es/blog/mastering-tabi-settings/#encoded-email) para protección contra spam.
 - [Mapa de sitio web estilizado y legible por humanos](https://welpo.github.io/tabi/sitemap.xml).
 - [Feed de Atom estilizado y legible por humanos](https://welpo.github.io/tabi/es/atom.xml).

content/projects/tabi/index.md

@@ -25,6 +25,7 @@ social_media_card = "social_cards/projects_tabi.jpg"
 - [Comprehensive multi-language support](https://welpo.github.io/tabi/blog/faq-languages/#how-does-tabi-handle-multilingual-support). Add as many languages as you wish.
 - Support for [comments using giscus, utterances, Hyvor Talk, or Isso](https://welpo.github.io/tabi/blog/comments/).
 - Code syntax highlighting with colours based on [Catppuccin](https://github.com/catppuccin/catppuccin) Frappé.
+- [Local search](https://welpo.github.io/tabi/blog/mastering-tabi-settings/#search) with an accessible, multi-lingual interface.
 - [KaTeX](https://katex.org/) support for mathematical notation.
 - [Stylized and human readable Atom feed](https://welpo.github.io/tabi/atom.xml).
 - [Stylized and human readable sitemap](https://welpo.github.io/tabi/sitemap.xml).

i18n/ca.toml

@@ -14,6 +14,13 @@ privacy = "política de privadesa"
 site_statistics = "estadístiques del lloc"
 sitemap = "mapa del lloc"
 
+# Search.
+search = "Cercar"
+search_icon_title = "Fes clic o prem $SHORTCUT per obrir la cerca"  # $SHORTCUT will be replaced with the actual keyboard shortcut.
+clear_search = "Esborrar cerca"  # Title of the X icon next to search input.
+result = "resultat"  # "1 result"
+results = "resultats"  # "3 results" (also used for 0 results).
+
 # Navigation.
 read_more = "Llegir més"
 post = "entrada"

i18n/de.toml

@@ -18,6 +18,13 @@ privacy = "datenschutzrichtlinie"
 site_statistics = "seitenstatistiken"
 sitemap = "seitenübersicht"
 
+# Search.
+search = "Suchen"
+search_icon_title = "Klicken oder $SHORTCUT drücken, um die Suche zu öffnen"  # $SHORTCUT will be replaced with the actual keyboard shortcut.
+clear_search = "Suche löschen"  # Title of the X icon next to search input.
+result = "ergebnis"  # "1 result"
+results = "ergebnisse"  # "3 results" (also used for 0 results).
+
 # Navigation.
 read_more = "Weiterlesen"
 post = "beitrag"

i18n/en.toml

@@ -14,6 +14,13 @@ privacy = "privacy policy"
 site_statistics = "site statistics"
 sitemap = "sitemap"
 
+# Search.
+search = "Search"
+search_icon_title = "Click or press $SHORTCUT to open search"  # $SHORTCUT will be replaced with the actual keyboard shortcut.
+clear_search = "Clear search"  # Title of the X icon next to search input.
+result = "result"  # "1 result"
+results = "results"   # "3 results" (also used for 0 results).
+
 # Navigation.
 read_more = "Read more"
 post = "post"

i18n/es.toml

@@ -14,6 +14,13 @@ privacy = "política de privacidad"
 site_statistics = "estadísticas del sitio"
 sitemap = "mapa del sitio"
 
+# Search.
+search = "Buscar"
+search_icon_title = "Haz clic o usa $SHORTCUT para abrir la búsqueda"  # $SHORTCUT will be replaced with the actual keyboard shortcut.
+clear_search = "Borrar búsqueda"  # Title of the X icon next to search input.
+result = "resultado"  # "1 result"
+results = "resultados"  # "3 results" (also used for 0 results).
+
 # Navigation.
 read_more = "Leer más"
 post = "entrada"