Поиск

Docara строит поисковый индекс вместе со статическим сайтом. Поиск работает в браузере, не отправляет запросы во внешний сервис и не требует серверной базы данных.

Включение

Добавьте настройки в docara.json:

{
  "schema": "docara.site.v1",
  "search": {
    "enabled": true,
    "indexed": true
  }
}

• enabled показывает кнопку и диалог поиска на страницах текущей области;
• indexed добавляет страницы области в индекс.

Обе настройки наследуются через section.json и файл страницы. Ветка поддерживает $reset так же, как branding, layout, navigation и settings (см. пример). Изменение настроек поиска требует полной сборки.

Исключение страниц

Чтобы не показывать раздел в результатах, задайте в его section.json:

{
  "schema": "docara.section.v1",
  "search": { "indexed": false }
}

navigation.hidden и search.indexed решают разные задачи. Страница может не занимать место в меню, но оставаться доступной по прямой ссылке и через поиск. Обе настройки не являются контролем доступа: собранная HTML-страница и сам JSON-индекс остаются публичными статическими файлами. Не публикуйте в portable site секретные или закрытые данные.

Если поиск включён для locale, но все его страницы исключены, сборка останавливается с SEARCH_INDEX_LOCALE_EMPTY до очистки предыдущего output.

Что индексируется

В индекс входят:

• title и description страницы;
• метки tags из начала страницы;
• путь разделов из того же дерева, что используется меню;
• заголовки Markdown;
• видимый текст абзацев, списков, таблиц и code blocks;
• текстовые атрибуты Smart-компонентов: title, text, supporting-text, label и description.

Текст берётся из готовой страницы, поэтому отдельный список компонентов для поиска не нужен. script, style, template, скрытые узлы (hidden, aria-hidden="true") и технические параметры не индексируются. Меню, содержание страницы, хлебные крошки и переходы строятся из того же дерева страниц, что и путь разделов в индексе.

Синонимы: метки страницы

Поиск находит страницу по словам, которые в ней есть. Если читатели ищут другим словом, например «деплой» вместо «публикация» или «иконки» вместо «значок», добавьте эти слова в метки tags в начале страницы:

---
tags: [деплой, публикация, deploy]
---

# Публикация сайта

Метки попадают в индекс поиска. Страница с меткой, совпавшей с запросом, стоит в результатах выше страниц, где это слово встречается только в тексте или в подзаголовках, но ниже страницы, в названии которой есть это слово. На самой странице метки не видны.

Метка — одно слово или несколько слов через -: строчные буквы любого алфавита, цифры, ., _ и -, например деплой, i18n или material-symbols. Заглавные буквы и пробелы останавливают сборку с FRONT_MATTER_TAG_INVALID. Поиск сравнивает начало слова, поэтому метка иконки находит и запрос «иконк», но не «иконка»: добавьте нужные формы слова отдельными метками.

Работа в браузере

Индекс загружается только после первого открытия диалога. Нажмите кнопку «Поиск» или Cmd/Ctrl + K, введите минимум два символа и используйте стрелки и Enter для перехода. Escape закрывает диалог и возвращает фокус на кнопку.

Ссылка, которая открывает поиск

Чтобы ссылка в тексте открывала диалог поиска, укажите в Markdown вместо адреса #docara-search:

Не нашли ответ? [Откройте поиск](#docara-search).

Так можно написать любую ссылку: в абзаце, в списке, кнопку в Hero или CTA. Сборка превращает её в ссылку на главную страницу языка с атрибутом data-docara-search-open; по нему _docara/search.js открывает диалог, как кнопка «Поиск». Без JavaScript поиск не работает, поэтому ссылка ведёт на главную. Если на странице поиск выключен (search.enabled: false), это обычная ссылка на главную. Такая же ссылка стоит на встроенной странице 404.

Поиск нормализует регистр, Unicode и русские е/ё. Результаты ранжируются по title, меткам tags, заголовкам, description и основному тексту. Это локальный полнотекстовый поиск с prefix matching; он пока не заявляет исправление опечаток, морфологию или семантический AI-поиск.

Если поиск не работает

1. Убедитесь, что search.enabled: true дошло до resolved page plan.
2. Проверьте наличие _docara/search-index.json и _docara/search.js.
3. Запустите php vendor/bin/docara verify-static build_production.
4. Исправьте первый search error code и пересоберите сайт.

Сообщение «Ничего не найдено» означает валидный пустой результат. Сообщение «Поиск временно недоступен» означает, что индекс не загрузился или нарушил закреплённый контракт.

См. также

• Метаданные страницы — где задаются метки tags
• Коды ошибок поиска
• Меню и разделы — скрытые страницы и поиск