Собираем Docs-as-Code: GitLab CI, Docusaurus и поиск. Как мы сделали базу знаний. Часть 3

В прошлой части я объяснил, почему мы выбрали Docusaurus. Выбор сделан, но «движок» сам по себе — это просто куча JS-файлов. Чтобы всё это реально заработало в компании, нужно было подружить его с нашими репозиториями, настроить автоматическую сборку и заставить поиск работать молниеносно.

Рассказываю, как мы это «приготовили» в СОФТОНИТ.

Архитектура: Одна «витрина» — много источников
Главная идея Docs-as-Code: документация лежит рядом с кодом, мы пишем код, обновляем документацию и клиенты видят обновленную документацию на сайте без танцев с бубном. У нас несколько продуктов (например, Управление IT-отделом 8), и у каждого продукта свой репозиторий в GitLab.

Я не хотел заставлять разработчиков копировать файлы вручную. Все должно быть просто для разработчиков. Поэтому мы создали отдельный репозиторий для документации, который работает как «агрегатор».

Как это работает:

1. В репозитории агрегаторе есть файл конфигурации repos.json, где перечислены все наши проекты и ветки откуда надо брать документацию (как правило это ветка main).
2. GitLab CI при запуске в репозитории агрегаторе идет в эти репозитории доноры и забирает папку docs у каждого продукта, копируя в общую структуру Docusaurus. В каждом репозитории есть папка docs с документацией в markdown.
3. Происходит «магия» со слагами (slugs) и ID для каждой статьи (транслитерация адресов URL статей), чтобы ссылки не бились.
Всё это пакуется и собирается общая база знаний, а затем она копируется на сервер.
4. Затем обновляется поисковый индекс.

Разбор полетов: Наш GitLab CI/CD

Ниже — ключевые этапы нашей сборки. Я не буду уходить в дебри, остановлюсь на важных нюансах.

- Этап синхронизации (Sync): Здесь мы используем node:24-alpine. Главная хитрость — обход прокси для внутреннего GitLab. Мы прописываем IP бэкенда прямо в ~/.ssh/config. Скрипт перебирает repos.json, клонирует репозитории и вытягивает Markdown-файлы.
- Сборка (Build): Стандартный npm run build. На выходе получаем готовую статику в папке build/.
- Деплой (Deploy): Используем старый добрый rsync через SSH. Это быстрее и надежнее для обновления только измененных файлов. Работает, кстати, такое очень быстро.
- Индексация (Index): А вот тут самое интересное.
Поиск: Почему Meilisearch, а не Algolia?

В прошлой статье я хвалил Algolia, но в итоге мы развернули Meilisearch. Почему?

- Полный контроль: Всё крутится на нашем сервере.
- Скорость: Он быстрый.
- Стоимость: Для наших объемов это бесплатно, при этом качество выдачи не уступает облачным гигантам.

Сейчас на docs.softonit.ru уже можно посмотреть результат.

А как вы решаете вопрос с обновлением общей документации из разных репозиториев? Делаете мульти-проектные пайплайны или тоже живете на расписании? 👇