Интеграция с поисковыми системами

Чтобы включить в документации поддержку поисковой системы, нужно указать в настройках секцию search.
После этого в интерфейсе в правом верхнем углу должен появиться элемент поиска.

По умолчанию поддерживается локальный поиск, реализованный с помощью lunrjs

search:
  provider: local

Локальный поиск

Конфигурация

search:
  provider: local
  toleranse: 2
  confidense: phrased

confidense

Переключает режим дополнительного ранжирования результатов поиска.

confidense: phrased - значение по умолчанию. Дополнительно ранжирует результаты по длине найденной фразы.

confidense: sparsed - Использует обычное ранжирование из LunrJS. Т.е. просто считает количество найденных в документе слов, не учитывая расстояние между ними.

tolerance

Переключает диапазон поискового запроса.

tolerance: 0 - Ищет точное совпадение слов.

tolerance: 1 - Если результатов tolerance=0 недостаточно, ищет “хвостики”. т.е word*.

tolerance: 2 - (по умолчанию) Если результатов tolerance=1 недостаточно, ищет “шапочкки” т.е *word*.

Архитектура

LunrJS строит поисковый индекс при сборке документации и ищет по нему синхронно.
Это накладывает на систему ряд ограничений:

Объем

Поисковый индекс может быть достаточно большим. В среднем он занимает в три раза больше места чем объем текстовой информации в индексируемых документах.

При этом индекс заново инициализируется на каждой новой вкладке документации (в момент фокуса в элементе поиска).

Это может негативно сказаться на объеме памяти, занимаемой браузером и на скорости инициализации результатов поиска.

В случае если поисковый индекс превышает 100Mb, стоит подумать об интеграции с другой поисковой системой.

Объем индекса можно посмотреть в директории собранной документации в разделе _search/<lang>/index.js.

Синхронность

Из-за того что LunrJS имеет синхронную реализацию, основная часть его логики вынесена в WebWorker.

У WebWorker есть ряд ограничений по работе с файловой системой, если вы открываете документацию полностью локально (file:///some-documentation).

Реализация в Diplodoc старается обойти эти ограничения, но не гарантирует, что в будущих политиках браузера все будет работать.

Проблемы

О проблемах в локальном поиске стоит сообщать в issues соответствующего проекта.