Поиск с Algolia

Algolia — облачная система поиска для быстрого и релевантного поиска по документации Diplodoc. Подходит для больших объемов данных, обеспечивает мгновенную выдачу результатов и легко интегрируется во фронтенд документации.

Исходный код и дополнительные инструкции расширения Algolia:
https://github.com/diplodoc-platform/algolia-extension

Для регистрации аккаунта Algolia может понадобиться VPN.

Быстрый старт

1. Зарегистрируйтесь в Algolia
   Перейдите на algolia.com и создайте аккаунт. После этого получите App ID, Write API Key и Search API Key для вашего приложения.
   (Подробнее см. раздел “Регистрация и настройки Algolia”)

2. Установите Diplodoc CLI и расширение Algolia (глобально)

   npm install -g @diplodoc/cli
   npm install -g @diplodoc/algolia
   

   (Подробнее о вариантах установки — в разделе “Установка”)

3. Сконфигурируйте поиск в .yfm
   В корневом .yfm пропишите:

   search:
     provider: algolia
     appId: <ваш app id>
     searchKey: <ваш search key>
     index: true
   

   (Пример с расширенными настройками — см. “Пример расширенной настройки”)

4. Передайте ключи и запустите сборку
   Для безопасной сборки передавайте Write API Key через флаг CLI:

   yfm -i ./docs -o ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia" --api-key "your-write-key"
   

Регистрация и настройки Algolia

1. Зарегистрируйтесь на algolia.com (может потребоваться VPN).
2. В панели Algolia создайте приложение (Application) и получите:
   • App ID ― идентификатор приложения
   • Write API Key ― секретный ключ для индексации данных
   • Search API Key ― ключ для поиска на клиенте
3. Имя индекса (indexName) можно не задавать, по умолчанию "docs".

Установка

Существует два варианта установки расширения для поиска Algolia:

• Глобальная установка — подходит для большинства типовых сценариев, если вы просто хотите собрать документацию с поддержкой облачного поиска.
• Локальная установка в репозитории — рекомендуется, если вы используете собственные плагины, дорабатываете cli или работаете в команде с общим package.json.

Глобальная установка:

npm install -g @diplodoc/cli
npm install -g @diplodoc/algolia

Запуск сборки с расширением:

yfm -i ./docs -o ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia" --api-key "your-write-key"

Локальная установка в проекте @diplodoc/cli:

npm install @diplodoc/algolia

Запуск сборки с расширением:

npm start -- -i ./docs -o ./docs-out --extensions @diplodoc/algolia --api-key "your-write-key"

Источники для передачи параметров

Параметры расширения можно задавать через CLI, переменные окружения и файл .yfm:

Пример расширенной настройки

search:
  provider: algolia
  appId: <ваш app id>
  indexName: docs
  index: true
  searchKey: <ваш search key>
  indexSettings:
    searchableAttributes:
      - title
      - content
      - headings
      - keywords
    attributesToHighlight:
      - title
      - content
  querySettings:
    hitsPerPage: 10
    attributesToRetrieve:
      - title
      - content
      - url
      - section

Сборка и индексация

• По умолчанию расширение создает локальные индексы в каталоге _search вашей выходной папки. Эти индексы доступны для локального поиска и не загружаются в облако.
• Если в конфиге задан параметр index: true (или используется CLI-флаг --index), то при каждой сборке документации индекс будет не только формироваться локально, но и автоматически загружаться (обновляться) в Algolia после сборки.
• Если вы хотите разделить эти процессы — например, сначала собрать документацию, проверить результат, а индекс загружать только после финальной проверки или отдельно по расписанию — настройте сборку без параметра index (или явно с index: false). Тогда при сборке создаются только локальные индексы. Позднее для загрузки или обновления индекса в облако используйте отдельную команду:

yfm index -i ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia" --api-key "your-write-key"

Частые вопросы и проблемы

• Поиск не работает — проверьте, что searchKey корректно передан в конфиге.
• Ошибка при индексации — проверьте правильность и способ передачи write apiKey.
• Данные не появляются в Algolia — убедитесь, что выставлен параметр index: true в конфиге или используется ключ --index при запуске.