В прошлой части я рассказывал, как наша база знаний на Битриксе превратилась в источник головной боли. Неудобный редактор, квесты с загрузкой картинок и, главное, полный рассинхрон документации с кодом. Терпеть это дальше было нельзя.
Решение принято — переезжаем на Docs-as-Code. Остался «пустяк»: выбрать движок, на котором всё это будет работать. И тут начинается самое интересное.
TL;DR для тех, у кого нет времени:
❗️ Задача: Найти быстрый и удобный генератор статических сайтов с мощным поиском, чтобы клиенты и сотрудники не страдали.
🔥 Ключевые критерии: Скорость сборки, качество поиска (в идеале, с поддержкой Algolia), наличие плагинов и живое комьюнити.
💡 Победитель: Docusaurus. Он оказался оптимальным по всем пунктам.
А теперь подробнее, как я к этому пришел.
Подход к выбору: как не потратить на тесты целую неделю
Сразу скажу честно: я не стал разворачивать каждый из десятка популярных инструментов на тестовом стенде. Это очень долго. Неделя рабочего времени, потраченная на «поиграться», это слишком дорого.
Мой подход проще. Вместо того чтобы закапываться в код, я анализировал проекты и задавал себе несколько не сложных вопросов:
- Насколько живой проект? Кто за ним стоит? Есть ли свежие коммиты, активные обсуждения, понятная дорожная карта? Выбирать инструмент, который может умереть через год плохая стратегия.
- Что говорят люди? Я полез читать обсуждения на Reddit, Habr и в профильных чатах. Реальный опыт пользователей часто говорит больше, чем рекламные лозунги на главной странице.
- Насколько легко найти решение проблемы? Я специально гуглил типовые проблемы вроде «How to add search to [название движка]» или «[название движка] custom theme». Если в топе выдачи официальная документация и пара решенных кейсов на Stack Overflow — это хороший знак. Если же там только заброшенные ветки форумов, я проходил мимо.
- Что используют известные сервисы или сайты у себя? Искал в интернете и смотрел кто, что использует. Если проект используется крупным и известным сайтом, то это прям круто-круто.
Первое подозрение о том, что я не буду долго выбирать генератор статических сайтов произошло когда я сравнил техническую документацию Сбера и Т-Банка:
Если вам кажется, что базы знаний похожи — вам не кажется. Они действительно используют один и тот же генератор Docusaurus. Щелкнул внутри базы знаний правой кнопкой, далее «Просмотреть код страницы» и поискать слово «Docusaurus». Разработали Docusaurus в Meta (признана экстремистской и запрещённой на территории РФ).
Еще понравился Diplodoc от Яндекса. Они пишут всю свою документацию в Diplodoc.
Мои главные критерии
Я сформировал шорт-лист требований, которые были критичны именно для нашего проекта:
- Скорость сборки. Документация у нас объемная и будет расти. Каждая минута, которую разработчик ждет, пока соберутся изменения, — это деньги компании. Сборка должна быть быстрой.
- Поиск, который работает. Поиск — это лицо документации. Если пользователь не может найти нужную статью, считай, ее не существует. Старый поиск на Битриксе научил меня, что на этом экономить нельзя. Я сразу целился в интеграцию с Algolia — это один из лучших поисковых сервисов, и многие современные движки поддерживают его «из коробки».
- Экосистема и плагины. Хочется иметь возможность легко добавлять новые фичи: возможность кастомизации, диаграммы Mermaid, настройка темы. Голая система без плагинов быстро упрется в потолок.
- Активное комьюнити. Когда что-то пойдет не так (а оно пойдет), важно иметь место, где можно спросить совета.
Кто был в списке кандидатов?
Мой финальный шорт-лист выглядел так: Diplodoc, Hugo, MkDocs, Fumadocs и Docusaurus.
- Diplodoc: Работает на Node.js и React, выглядит неплохо, использует все плагины от markdown-it и немного своих. Можно развернуть как в облаке, так и на собственном сервере. Из минусов их yfm-расширение markdown показалось мне слишком похожим на HTML, а не markdown, но это дело вкуса.
- Hugo: Написан на Go, известен как самый быстрый генератор сайтов. Это огромный плюс. Но он больше про блоги и сайты-визитки. Чтобы сделать из него крутую базу знаний, пришлось бы много допиливать руками. Голый и быстрый, но требует много любви.
- MkDocs: Старый и проверенный боец на Python. Простой, понятный, куча тем и плагинов. Но по ощущениям, он немного застрял в прошлом. Вроде всё есть, но выглядит не так современно, как хотелось бы.
- Fumadocs: Новый и модный игрок. Выглядит очень круто, быстрый, построен на современных технологиях (Next.js). Я серьезно на него смотрел, но сработал мой внутренний скептик. Проект молодой, комьюнити пока небольшое. Брать его в продакшен для ключевой системы показалось рискованным, но выглядит футуристично.
Почему в итоге Docusaurus?
Docusaurus победил, потому что он попал в золотую середину.
Во-первых, за ним стоит известный разработчик, что дает уверенность в долгосрочном развитии проекта. Комьюнити огромное, документация отличная.
Во-вторых, он изначально заточен под создание именно баз знаний. Его выбрали в Сбере и Т-Банке не просто так. Там есть всё, что нужно, прямо из коробки: версионирование, кастомизация, удобная структура и плагины. Плагинов, кстати, не так много, но там есть все что нужно.
И в третьих, что стало решающим фактором — это идеальная интеграция с поиском Algolia. Она настраивается за пару часов, и ты получаешь поиск, который на три головы выше любого встроенного решения.
Да, он не такой молниеносный, как Hugo, потому что построен на React и Node.js. Но его скорость сборки более чем приемлема, а гибкость и функциональность с лихвой перекрывают этот небольшой минус.
Еще, из интересного, в Docusaurus можно вести блоги. Люди хранят записи в блоге на github, затем при пушах выполняют github actions, которые разворачивают блог. Интересная возможность.
Итак, выбор сделан. Впереди самое интересное: перенос старых статей, настройка CI/CD и запуск новой базы знаний в бой. Об этом расскажу в следующих частях.
А вы согласны с моим выбором? Может, я упустил какой-то крутой инструмент, пока анализировал рынок? Делитесь в комментариях, на чём живет ваша документация. 👇
