Developer Guides: мы отказались не от гайдов, а от Flude в них — и передумали
· 2 min read
В прошлой статье мы обещали рассказать про интеграцию руководств разработчика. Мы дважды меняли подход к сборке Developer Guides. Сначала мы вынесли их за пределы генератора Flude. Потом реальность заставила нас пересмотреть это решение.
Первый заход: монолитный HTML-генератор
На старом HTML-стеке один громоздкий инструмент собирал API-справочник вместе с гайдами. Руководства закрывали типовые сценарии вроде быстрого старта или создания собственных проектов. Они также включали подборки статей про особенности конкретных SDK. Такие вещи относятся к работе с платформой в целом и требуют отдельного текстового описания.
Мы перенесли эту монолитную склейку в первую версию Flude по инерции. Старая схема казалась рабочей. Тематика гайдов осталась прежней, поэтому никто не задумывался о разделении процессов.
Второй заход: иллюзия простого Markdown
При переходе на генератор статических сайтов мы решили убрать гайды из зоны ответственности Flude. Логика казалась железобетонной. Пусть наш парсер занимается сложным извлечением API. Рукописные гайды представляют собой обычный текст в Markdown, который статический генератор соберет без посторонней помощи. Перевод из HTML потребовал минимальной автоматизации.
Гайды переехали в отдельную директорию. SSG подхватывал их напрямую без всякой предобработки. Flude полностью выпала из этого процесса. Разделение выглядело красиво на бумаге, поскольку два независимых источника контента встречались только на готовой странице.
Возвращение в единый процесс
Спустя время мы заметили серьезную проблему с навигацией. Гайды ничего не знали о страницах API-справочника, а справочник понятия не имел о существовании гайдов. Ссылки на классы или методы вели в никуда, если страница еще не сгенерировалась. Они тихо умирали при изменении путей во время пересборки. Ни один из процессов не видел соседа и не мог предупредить об ошибке.
Мы вернули Developer Guides под управление Flude, однако сделали это в новом формате. Движок больше не рендерит их напрямую. Теперь он проверяет корректность файлов и отслеживает целостность перекрестных ссылок. Итоговую сборку портала продолжает выполнять SSG. Flude встраивается в этот конвейер отдельным шагом валидации. Обе системы существуют внутри единого процесса, который замечает битые ссылки до публикации.
Красивая архитектура на бумаге часто разбивается о реальные требования. Разделение систем неизбежно требует создания надежных мостов между ними. В следующем материале мы разберем типизированные модели сущностей (Typed Models), которые помогли навести порядок в разрозненных данных.