Поиск по документации

Удобство чтения HTML-документации можно дополнительно повысить, если предоставить пользователю возможность вводить поисковые запросы и переходить к нужным разделам. Такой поиск хоть и не заменяет продуманную структуру документации, но, как правило, хорошо её дополняет.

В Собираку включена интеграция с библиотекой Pagefind, которая реализует поиск по текущему документу документации. Поиск работает на JavaScript и полагается на файлы, сгенерированные во время сборки.

Поиск включается настройкой web.search.engine в конфиге проекта. Для корректной работы и отображения поиска его поддержка должна быть добавлена в используемую тему оформления HTML. Например, документация, которую вы читаете сейчас, собрана с темой sobiraka2025, в которую такая поддержка уже добавлена.

Принцип работы #

Во время сборки документации Собирака формирует упрощённую (очищенную от форматирования) версию каждой страницы и передаёт её библиотеке Pagefind, которая формирует свой поисковый индекс. Когда пользователь вводит поисковый запрос, код Pagefind подгружает файлы поискового индекса с того же домена, на котором размещена документация. После этого пользователю показывается список подходящих фрагментов текста вместе со ссылками на соответствующие страницы.

Сама Собирака не генерирует отдельную страницу с результатами поиска, хотя подобную страницу возможно реализовать с помощью JavaScript в теме оформления HTML. Тема sobiraka2025 (используется в документации, которую вы читаете сейчас) не создаёт отдельную страницу, а показывает результаты прямо под полем поиска без перезагрузки страницы.

Когда вы открываете собранную документацию в виде HTML-файлов на компьютере, поиск может не работать из-за политик безопасности в современных браузерах. Чтобы проверить работу поиска, разместите документацию на реальном домене в интернете или настройте локальный тестовый сервер.

Настройка индексации текста #

С помощью настройки web.search.skip_elements можно исключить из поиска содержимое определённых типов элементов. Например, в зависимости от специфики проекта, вы можете исключить из поиска все таблицы, все примеры кода или все математические формулы.

Исключённые элементы не будут учитываться ни при анализе поискового запроса, ни при отображении списка результатов.

Каждая ссылка в результатах поиска не обязательно должна вести в начало страницы документации — иногда она может указывать на подраздел. (Например, по запросу «каждая ссылка» можно найти конкретно этот абзац.)

По умолчанию Собирака не включает в результаты поиска ссылки на подзаголовки. С помощью настройки web.search.link_target можно разрешить включать все подзаголовки вплоть до самых мелких (значение h6) или ограничить глубину ссылок определённым максимальным уровнем (значения h2–h5).