В прошлой части я объяснил, почему мы выбрали Docusaurus. Выбор сделан, но «движок» сам по себе — это просто куча JS-файлов. Чтобы всё это реально заработало в компании, нужно было подружить его с нашими репозиториями, настроить автоматическую сборку и заставить поиск работать молниеносно.
Рассказываю, как мы это «приготовили» в СОФТОНИТ.
Архитектура: Одна «витрина» — много источников
Главная идея Docs-as-Code: документация лежит рядом с кодом, мы пишем код, обновляем документацию и клиенты видят обновленную документацию на сайте без танцев с бубном. У нас несколько продуктов (например, Управление IT-отделом 8), и у каждого продукта свой репозиторий в GitLab.
Я не хотел заставлять разработчиков копировать файлы вручную. Все должно быть просто для разработчиков. Поэтому мы создали отдельный репозиторий для документации, который работает как «агрегатор».
Как это работает:
- В репозитории агрегаторе есть файл конфигурации repos.json, где перечислены все наши проекты и ветки откуда надо брать документацию (как правило это ветка main).
- GitLab CI при запуске в репозитории агрегаторе идет в эти репозитории доноры и забирает папку docs у каждого продукта, копируя в общую структуру Docusaurus. В каждом репозитории есть папка docs с документацией в markdown.
- Происходит «магия» со слагами (slugs) и ID для каждой статьи (транслитерация адресов URL статей), чтобы ссылки не бились.
- Всё это пакуется и собирается общая база знаний, а затем она копируется на сервер.
- Затем обновляется поисковый индекс.
Разбор полетов: Наш 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-scraper. После каждого деплоя запускается контейнер, который обходит наш сайт docs.softonit.ru, парсит заголовки и текст, и обновляет поисковый индекс.
Что получилось в итоге
Сейчас на docs.softonit.ru уже можно посмотреть результат.
- Главная страница (Home page): Пришлось её кастомизировать. Теперь это удобный хаб, где выведены все наши проекты с иконками. Сразу понятно, куда идти.
- Темная и светлая темы: Мелочь, но разработчики (и я в том числе) ценят возможность переключиться на Тёмную тему (Dark mode) вечером.
- Скорость: Всё «летает», так как это статичный сайт. Никаких тормозов админки Битрикса.
Честный «косяк»: Проблема триггеров
Буду честен — сейчас система не идеальна. Проблема: Сборка запускается только в репозитории самой документации. Если разработчик изменил файл в репозитории продукта, документация на сайте сама не обновится.
Как решаем сейчас: Запуском сборки по расписанию (Schedule) раз в день. Это «костыль», который нивелирует этот минус, но лишает нас оперативности. Т.е. документация не мгновенно обновляется на сайте, а раз в день. Если у вас есть проверенный рецепт, как из десяти разных репозиториев красиво пинать один головной в GitLab без создания «спагетти» из вебхуков — пишите в комментариях.
Переезд и 301-е редиректы
Мы не просто выключили старую базу знаний. Чтобы не потерять SEO и не подвести клиентов, у которых статьи в закладках, мы планомерно прописываем 301 редиректы (Permanent Redirect). Старая статья на Битриксе теперь ведет на конкретную новую страницу в Docusaurus. Не делаем все сразу, а по частям, чтобы не упасть в поиске.
Итог: Мы получили гибкую, современную и очень быструю систему. Docs-as-Code — это не просто модно, это реально экономит время на поддержке актуальности данных.
А как вы решаете вопрос с обновлением общей документации из разных репозиториев? Делаете мульти-проектные пайплайны или тоже живете на расписании? 👇