Configurar búsquedas

En cada página del libro se incluye un icono de búsqueda en la barra superior. Pulsando en él, se abre una caja para introducir textos de búsqueda.

A medida que tecleamos el texto a buscar, se va mostrando una lista de resultados.

Podemos pulsar con el ratón en alguna de las entradas de la lista para ir a esa página, o bien pulsar la tecla Esc para abandonar. También podemos usar las teclas de flecha ↑ ↓ para desplazarnos por la lista y pulsar enter para seleccionar el elemento resaltado.

Podemos desactivar esta función desde el archivo de configuración book.toml

[output.html.search]
enable = true       

La tabla [output.html.search] proporciona opciones para configurar el proceso:

[output.html.search]

enable = true            # activa las búsquedas
limit-results = 30       # máximo número de resultados
teaser-word-count = 30   # número de palabras usadas en los resultados
use-boolean-and = true   # deben coincidir todas las palabras
boost-title = 2          # importancia de coincidencias en títulos
boost-hierarchy = 1      # importancia de coincidencias en nombres de páginas
boost-paragraph = 1      # importancia de coincidencias en texto
expand = true            # aceptar coincidencia con términos más largos
heading-split-level = 3  # nivel de cabecera al que enlazar
copy-js = true           # incluir Javascript de búsquedas

las opciones son:

• enable: Activar las búsquedas. Por defecto es true.

• limit-results: Máximo número de resultados. Por defecto es 30.

• teaser-word-count: Número de palabras usadas en cada entrada de la lista de resultados. Por defecto es 30.

• use-boolean-and: Si es true, todas las palabras de búsqueda deben encontrarse en los resultados. Por defecto es false.

• boost-title: Factor de importancia de cada resultado cuando el texto aparece en una cabecera. Por defecto es 2.

• boost-hierarchy: Factor de importancia de cada resultado cuando el texto aparece en la jerarquía de títulos. Por defecto es 1.

• boost-paragraph: Factor de importancia de cada resultado cuando el texto aparece en el texto. Por defecto es 1.

• expand: True si las coincidencias con palabras más largas deben considerarse válidas. Por defecto es true.

• heading-split-level: Pulsando en un resultado, se irá al párrafo de título de sección correspondiente. Por defecto se va hasta el nivel 3 (cabeceras que empiezan con ###) si existe.

• copy-js: Incluye los archivos JavaScript estándar de mdBook. Por defecto es true.

La tabla [output.html.search.chapter] permite configurar incluir o excluir capítulos o directorios por separado. Cada entrada de la tabla es una ruta a un archivo o directorio, seguida de una subtabla de configuraciones a aplicar a esa ruta. Se pueden solapar, tomando precedencia las rutas más específicas.

[output.html.search.chapter]

# Desactivar búsquedas para todos los capítulos en el directorio `carpeta1` 
"carpeta1" = { enable = false }

# Activar búsquedas para el capítulo `glosario`
"carpeta1/glosario.md" = { enable = true }

La opción enable activa o desactiva las búsquedas para los capítulos indicados. Por defecto es true. Esto no sobreescribe la configuración output.html.search.enable, que ha de ser true para cualquier búsqueda que deba estar activada.

Téngase cuidado al deshabilitar la indexación para determinados capítulos porque eso puede llevar a la confusión del usuario cuando busca términos y esperan que se encuentren. Esto solo debe usarse en circunstancias excepcionales en las que mantener el capítulo en el índice causará problemas con la calidad de los resultados de búsqueda.