Búsquedas¶

Material for MkDocs proporciona un función de búsqueda de texto en la barra de cabecera cuando nuestro proyecto está formado por más de un documento:

Introduciendo un texto en la caja de búsqueda, se muestra una lista desplegable de resultados, y pulsando sobre uno de ellos, se navega hacia la página correspondiente.

Búsqueda integrada¶

Material for MkDocs implementa las búsquedas mediante un complemento que se integra por defecto, sin que tengamos que hacer nada. Sin embargo, debe volver a agregarse a mkdocs.yml cuando se utilizan otros complementos:

plugins:
  - search

Incluye búsqueda multilingüe utilizando dos piezas de software, lunr y lunr-languages.

Funcionamiento¶

El complemento de búsqueda analiza el texto HTML generado y crea un índice de palabras para todas las páginas y secciones. En las visitas a la página web, este índice se descarga junto al texto de la página web.

Configuración¶

Cuando estamos desarrollando un proyecto, quizás queramos desactivar este complemento para agilizar el trabajo:

plugins:
  - search:
      enabled: false

Idioma¶

Los algoritmos de búsqueda están optimizados para el idioma especificado en la configuración del proyecto. Pero podemos establecer el idioma explícitamente:

plugins:
  - search:
      lang: es

... o incluso indicar varias lenguas:

plugins:
  - search:
      lang: 
      - es
      - en

Autocompletado¶

Cuando introducimos un texto de búsqueda, podemos activar la función de sugerencia de texto, que será aceptado pulsando la tecla Right

theme:
  features:
    - search.suggest

Resaltado¶

Cuando el usuario pulsa sobre uno de los resultados de búsqueda, se irá a la página correspondiente. Podemos hacer que los textos coincidentes se muestren resaltados activando lo siguiente:

theme:
  features:
    - search.highlight

Compartir resultados¶

Cuando se activa la compartir búsqueda, se muestra un botón de compartir junto al botón de cierre X de la caja de búsqueda, lo que permite copiar al portapapeles un enlace a la consulta de búsqueda actual y al resultado. Agregue las siguientes líneas a mkdocs.yml:

theme:
  features:
    - search.share

Relevancia¶

En el front matter de una página podemos establecer su relevancia en la lista de resultados:

---
search:
  boost: 2 
---

texto de la página

Un valor por encima de 1 incrementa la relevancia, y uno inferior, la disminuye:

---
search:
  boost: 0.5
---

Podemos excluir determinadas páginas de la búsqueda:

---
search:
  exclude: true
---

texto de la página

Excluir secciones y bloques¶

Si activamos el complemento attr_list:

markdown_extensions:
  - attr_list

Podemos excluir secciones añadiendo tras la cabecera un atributo especial incorporado por Material for MkDocs, data-search-exclude.

# Título

## Sección 1

Contenido incluido

## Sección 2 { data-search-exclude }

Contenido excluído

También podemos excluir un bloque:

# Título

Contenido incluido

Contenido excluido
{ data-search-exclude }