Внешний HTTP-поиск

Подключите любой поисковый сервис, который реализует HTTP-контракт Diplodoc. Например, ваш шлюз может преобразовывать запросы в запросы OpenSearch и возвращать результаты в формате ниже. Интерфейс документации не зависит от поискового движка.

Внешний HTTP-поиск доступен в @diplodoc/cli начиная с версии 5.69.0.

Настройка

Добавьте в .yfm проекта:

search:
  provider: external
  endpoint: https://search.example.com/docs/search
  options:
    project: reference
    version: v1

Для подсказок в шапке включите расширенную навигацию в toc.yaml, например:

navigation:
  header:
    rightItems:
      - type: search

Соберите документацию командой yfm build -i ./docs -o ./docs-out. Расширение поиска и пользовательский JavaScript не требуются.

Те же настройки можно передать через CLI:

yfm build -i ./docs -o ./docs-out \
  --search-provider external \
  --search-endpoint https://search.example.com/docs/search \
  --search-options '{"project":"reference","version":"v1"}'

Значения CLI имеют приоритет над соответствующими настройками .yfm. --search-options заменяет объект options целиком. --no-search или search.enabled: false отключает поиск; --search явно включает его.

endpoint поддерживает:

• Абсолютный HTTP(S)-адрес: https://search.example.com/docs/search.
• Путь от корня домена: /api/docs/search.
• Путь относительно корня опубликованной документации: api/search. Если документация размещена по адресу https://example.com/product/v1/, ручка будет доступна по адресу https://example.com/product/v1/api/search как из статьи, так и со страницы результатов.

Не используйте адрес без протокола вида //host, учетные данные в URL, фрагменты, пробелы и обратные слеши. Адрес и options - публичные настройки, которые попадают в собранный HTML. Учетные данные OpenSearch или другого движка должны оставаться на сервере.

Запрос

Браузер отправляет GET на endpoint с заголовком Accept: application/json:

Каждое свойство options становится дополнительным query-параметром. Допустимы строки, числа и логические значения; они преобразуются в строки. Query-параметры, уже указанные в endpoint, сохраняются, если их не заменяют options или параметры контракта. query, lang, count, page и tags зарезервированы: значения текущего запроса всегда имеют приоритет.

Пример запроса:

GET /docs/search?project=reference&version=v1&query=quick%20start&lang=ru&count=10&page=2&tags=api&tags=guide

Сервис должен фильтровать результаты по языку, возвращать запрошенную страницу и применять условие ИЛИ к нескольким тегам. Общее количество совпадений рассчитывается до пагинации. Если сервис не поддерживает фильтрацию по тегам, не добавляйте теги в ссылки поиска.

Ответ

Верните HTTP 200 с JSON-объектом:

{
  "items": [
    {
      "title": "Быстрый старт",
      "url": "/product/v1/ru/quickstart.html",
      "description": "Создайте свой первый проект документации.",
      "section": "Руководства"
    }
  ],
  "total": 12,
  "tagCounts": {
    "guide": 12
  }
}

items - массив результатов. Каждый элемент содержит строковые поля title, url, description и необязательное строковое поле section. Ссылки должны работать и из статьи, и со страницы поиска; предпочтительны пути от корня домена или абсолютные URL. Не возвращайте исходный ответ OpenSearch.

total - неотрицательное целое число, общее количество совпадений. Необязательный tagCounts сопоставляет тегам неотрицательные целые количества результатов. Если совпадений нет, верните {"items": [], "total": 0}.

Фильтр тегов заполняется из публичных тегов в метаданных страниц; технические теги с префиксом _ и теги страниц с noIndex исключаются.

Эта же ручка обслуживает подсказки: клиент запрашивает страницу 1 с нужным count и показывает ее результаты в выпадающем списке. Подсказки и полный поиск используют один формат ответа, отдельная ручка подсказок не нужна.

HTTP-ошибки, сетевые сбои и некорректный формат ответа обрабатываются как ошибки поиска. Автоматического переключения на локальный поиск нет.

Размещение и индексация

Запросы выполняются в браузере пользователя, а не на машине сборки. Для ручки на другом origin настройте CORS, разрешающий origin документации; если документация использует HTTPS, ручка тоже должна использовать HTTPS. Если в проекте или на хостинге используется ограничивающая CSP, разрешите worker и endpoint в этой политике. Внешний провайдер не ограничивает обращения к другим сервисам. HTTP-клиент использует стандартную браузерную политику credentials для своего origin и не добавляет заголовок авторизации.

CLI генерирует страницу результатов и поставляет HTTP-клиент. Он не обращается к ручке при сборке, не создает внешний индекс, не загружает документы и не управляет поисковым сервисом. Владелец сервиса отвечает за индексацию и ограничения видимости документов, включая метаданные noIndex и контроль доступа.