✨ feat: add search functionality (#250)

2024-01-08 01:00:52 +01:00
parent fcd0c34d19
commit 906bc9dec0
69 changed files with 11443 additions and 6 deletions
--- a/content/blog/javascript/index.ca.md
+++ b/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].
--- a/content/blog/javascript/index.es.md
+++ b/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].
--- a/content/blog/javascript/index.md
+++ b/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.
--- a/content/blog/mastering-tabi-settings/index.ca.md
+++ b/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ó.
--- a/content/blog/mastering-tabi-settings/index.es.md
+++ b/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.
--- a/content/blog/mastering-tabi-settings/index.md
+++ b/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.
--- a/content/projects/tabi/index.ca.md
+++ b/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).
--- a/content/projects/tabi/index.es.md
+++ b/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).
--- a/content/projects/tabi/index.md
+++ b/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).