---
metadata:
  - name: generator
    content: Diplodoc Platform v5.69.0
alternate:
  - https://diplodoc.com/docs/en/project/external-search.md
  - https://diplodoc.com/docs/ru/project/external-search.md
  - href: https://diplodoc.com/docs/ru/project/external-search.md
    type: text/markdown
    title: Markdown version
  - href: https://diplodoc.com/docs/ru/llms.txt?revision=2fe5233dbd898443f0f6a570a74b128c2371860b
    rel: describedby
updatedAt: '2026-11-11T14:06:35.000Z'
---
> **Documentation Index:** Fetch the complete configuration index at https://diplodoc.com/docs/ru/llms.txt?revision=2fe5233dbd898443f0f6a570a74b128c2371860b

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

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

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

## Настройка

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

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

Для подсказок в шапке включите [расширенную навигацию](https://diplodoc.com/docs/ru/project/navigation.md) в `toc.yaml`, например:

```yaml
navigation:
  header:
    rightItems:
      - type: search
```

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

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

```bash
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`:

| Query-параметр | Значение |
| --- | --- |
| `query` | Поисковая строка с URL-кодированием. Может быть пустой, например при фильтрации по тегам. |
| `lang` | Текущий язык документации, например `ru` или `en`. |
| `count` | Максимальное количество результатов на странице. |
| `page` | Номер страницы, начиная с `1`. |
| `tags` | Выбранный тег. Повторяется для нескольких тегов, отсутствует, если теги не выбраны. |

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

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

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

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

## Ответ

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

```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` и контроль доступа.