В мире разработки программного обеспечения документация часто становится тем самым «узким горлышком», которое тормозит adoption продукта. Разработчики тратят часы на настройку сложных статических генераторов сайтов, борьбу с зависимостями React или конфигурацию облачных платформ, вместо того чтобы писать полезный контент. Но что, если можно было бы просто создать папку, кинуть туда Markdown-файлы и получить профессиональный, быстрый и SEO-оптимизированный сайт документации, который к тому же «понимают» AI-агенты? Именно эту проблему решает новый инструмент под названием Blume.
Hayden Bleasel, эксперт из OpenAI, недавно выпустил Blume в версии 1.0.3. Это не просто еще один генератор статических сайтов, а полноценная экосистема, спроектированная с учетом новой реальности, где документация должна быть доступна не только людям, но и языковым моделям. Проект лицензирован под MIT, полностью открыт и работает на базе TypeScript. В этой статье мы подробно разберем, как Blume меняет подход к созданию технической документации, какие технологии использует «под капотом» и почему он может стать стандартом для open-source проектов.
01Что такое Blume и почему он важен?
Blume позиционируется как фреймворк для документации с нулевой конфигурацией (zero-config). Его философия проста: вы предоставляете контент, а инструмент берет на себя всю техническую сложность. В отличие от традиционных решений, где нужно писать шаблонный код (boilerplate) для настройки роутинга, темизации и поиска, Blume работает по принципу «Drop Markdown into a folder» (брось Markdown в папку).
Инструмент состоит из двух основных частей: командной строки (CLI) и библиотеки компонентов. Он сканирует папку с файлами Markdown или MDX, а затем генерирует production-готовый сайт документации. Этот сайт включает в себя навигацию, встроенный поиск, темизацию и даже автоматически генерируемые изображения Open Graph для социальных сетей. Конфигурация остается опциональной: вы можете начать с пустого файла или постепенно добавлять настройки по мере необходимости.
Важно отметить, что Blume — это не изолированный монолит. Он построен как TypeScript-монорепо, где основной пакет находится в packages/blume. Примечательно, что сама документация проекта Blume также построена с помощью Blume, что является отличным примером «собаки, которая сама себя кормит» (dogfooding). Для работы требуется Node.js версии 22.12 или новее, и проект поддерживает все популярные менеджеры пакетов: Bun, pnpm, npm и yarn.
02Как работает Blume под капотом
Чтобы понять мощь Blume, нужно заглянуть внутрь его архитектуры. На поверхности пользователь видит простой интерфейс, но под капотом Blume генерирует и управляет скрытым проектом на базе Astro. Astro — это современный фронтенд-фреймворк, известный своей производительностью и подходом «islands architecture», который минимизирует объем JavaScript, отправляемого в браузер.
Процесс сборки выглядит следующим образом:
- Загрузка конфигурации: CLI считывает файл
blume.config.ts. - Сканирование контента: Инструмент сканирует вашу папку с контентом и строит граф связей между страницами.
- Генерация проекта: Blume записывает полноценный Astro-проект в скрытую директорию
.blume/. - Рендеринг: Astro рендерит каждую страницу через единый маршрут-ловушку (catch-all route). Этот маршрут импортирует компоненты Blume, сгенерированные данные и ваши пользовательские переопределения.
Ключевое преимущество такого подхода — скорость разработки. При каждом запуске директория .blume/ пересоздается, но переписываются только измененные файлы. Это обеспечивает мгновенную горячую перезагрузку (hot reload) во время редактирования. Кроме того, базовая тема Blume не включает клиентский JavaScript-фреймворк. Это означает, что страницы по умолчанию набирают высокие баллы по метрикам Core Web Vitals, что критически важно для SEO и пользовательского опыта.
Если вам нужна полная контроль над кодом, Blume предлагает функцию eject. Команда blume eject выгружает runtime в виде самостоятельного Astro-приложения. Это снижает риск vendor lock-in (привязки к вендору) в долгосрочной перспективе, позволяя разработчикам продолжать работу с кодом напрямую, если функциональности Blume станет недостаточно.
03Быстрый старт: Установка и настройка
Одним из главных преимуществ Blume является минимальный порог входа. Настройка проекта занимает всего одну команду. Это делает его идеальным как для новых проектов, так и для миграции существующей документации.
npx blume initПосле инициализации вы получаете готовую структуру папок. Для запуска локального сервера разработки используется команда blume dev, которая запускает сервер с горячей перезагрузкой. Для создания финальной версии сайта, которая будет развернута на хостинге, используется blume build. Эта команда записывает статический HTML и локальный индекс поиска в директорию dist/.
Конфигурационный файл blume.config.ts написан на реальном TypeScript и валидируется схемой. Это означает, что редакторы кода (например, VS Code) будут подсвечивать ошибки еще до запуска сборки, что значительно упрощает отладку. Ниже приведен пример базовой конфигурации, которая поддерживает как локальные файлы, так и интеграцию с Notion:
import { defineConfig } from "blume";
export default defineConfig({
content: {
sources: [
{
type: "filesystem",
root: "docs",
},
{
type: "notion",
database: process.env.NOTION_DB,
},
],
},
});CLI Blume покрывает весь жизненный цикл проекта. Вот краткий обзор основных команд:
blume init— создание проекта (интерактивный режим по умолчанию).blume dev— запуск сервера разработки.blume build— сборка статического или серверного сайта.blume add— установка компонента источника из реестра.blume sync— повторное получение данных из удаленных источников.blume eject— выгрузка runtime в самостоятельное Astro-приложение.blume validate— проверка внутренних ссылок, якорей, активов и внешних ссылок.blume doctor— диагностика проблем с конфигурацией и контентом.
04AI-Ready by Design: Документация для людей и машин
Самая инновационная часть Blume — это его ориентация на AI. В эпоху агентов, которые читают документацию, чтобы помочь разработчикам, традиционные HTML-сайты становятся менее эффективными. Blume спроектирован так, чтобы быть «понятным» для AI-агентов с самого начала.
Каждая страница Blume возвращает сырой Markdown, если вы добавите .md к URL. Это позволяет агентам легко парсить контент. Кроме того, существует флаг, который генерирует файлы llms.txt и llms-full.txt. Эти файлы служат своего рода «картой» для AI, указывая, какие страницы доступны и как их структурировать.
Пользователи также могут копировать содержимое каждой страницы как Markdown или открывать его напрямую в ChatGPT, Claude или v0. Опционально, на странице может быть встроен помощник «Ask AI», который отвечает на вопросы читателей. Этот помощник работает через AI SDK и поддерживает различные бэкенды: Vercel AI Gateway, OpenRouter, Inkeep или любой endpoint, совместимый с OpenAI.
Еще одна мощная функция — хостинг сервера протокола контекста модели (MCP). Это позволяет таким инструментам, как Claude Code, Cursor и VS Code, читать документацию напрямую. Вы можете добавить MCP-сервер с помощью простой команды:
claude mcp add --transport http your-docs https://docs.example.com/mcpЭтот сервер предоставляет четыре инструмента только для чтения:
search_docs— поиск по документации.get_page— получение содержимого конкретной страницы.list_pages— список всех страниц.get_navigation— получение структуры навигации.
05Сравнение с альтернативами
Чтобы оценить место Blume на рынке, давайте сравним его с тремя популярными подходами к созданию документации: Mintlify, Docusaurus и Astro Starlight.
| Параметр | Blume | Mintlify | Docusaurus | Astro Starlight |
|---|---|---|---|---|
| Тип | Open-source CLI + фреймворк | Хостимая коммерческая платформа | Open-source SSG | Open-source тема для Astro |
| Лицензия | MIT, бесплатно | Проприетарная; платный тариф Pro | MIT, бесплатно | MIT, бесплатно |
| Настройка | Нулевая конфигурация (папка Markdown) | На основе конфигурации, управляется | Скейлдинг + конфигурация React | Проект Astro + тема |
| Движок | Скрытый Astro + Vite | Проприетарный хостинг | React | Astro |
| Клиентский JS (базовая тема) | Отсутствует (статический HTML) | — | React runtime | Минимальный (острова) |
| llms.txt / llms-full.txt | Встроенный флаг | Автоматически генерируется | Плагин сообщества | Встроенный |
| Встроенный MCP-сервер | Да (4 инструмента только для чтения) | Да (автоматически размещается) | Не встроен | Не встроен |
| Путь выгрузки (Eject) | Самостоятельное Astro-приложение | Не применимо (хостинг) | Уже Astro | — |
Сильные и слабые стороны
Сильные стороны Blume:
- Нулевая конфигурация: Папка с Markdown превращается в полноценный сайт.
- Статический-first подход: Отсутствие клиентского JS в базовой теме улучшает Core Web Vitals.
- Встроенные AI-инструменты: llms.txt, Markdown на каждой странице, MCP-сервер и Ask AI.
- Типобезопасная конфигурация: Ошибки ловятся редактором до сборки.
- Путь выгрузки: Возможность перейти на standalone Astro-приложение снижает риски.
Слабые стороны:
- Новизна: Версия 1.0.3 означает, что экосистема еще молода.
- Требования к Node.js: Нужна версия 22.12+, что может быть проблемой для некоторых старых окружений.
- Зависимость от сервера: Функции вроде Ask AI и MCP требуют серверного адаптера.
- Самохостинг: Вы сами отвечаете за аналитику и настройку ассистентов.
- Интеграции: Пока меньше сторонних интеграций, чем у зрелых хостимых платформ.
06Примеры использования
Возможности Blume легко адаптируются под различные сценарии:
- API-продукты: Вы можете добавить спецификацию OpenAPI или AsyncAPI. Blume отрендерит интерактивную справочную систему с схемами, аутентификацией и плейграундом для запросов через Scalar.
- Библиотеки: Укажите Blume на ваши GitHub Releases. Каждая версия будет собираться в хронологическую временную шкалу changelog с RSS-лентой.
- Глобальная аудитория: Blume поддерживает 36 локалей, маршрутизацию, aware к локали, и макеты справа-налево (RTL) для арабских и ивритских языков.
- Смешанный контент: Вы можете комбинировать локальные файлы с удаленными MDX, Notion или Sanity. Все источники рендерятся через одни и те же компоненты.
07Что это значит на практике
Blume представляет собой сдвиг парадигмы в создании технической документации. Он устраняет барьеры входа, связанные с настройкой сложных фреймворков, и одновременно закрывает потребности современной AI-эпохи, делая документацию машиночитаемой. Для разработчиков из России и СНГ это особенно актуально, так как open-source решение позволяет избежать зависимости от зарубежных облачных платформ, которые могут быть недоступны или ограничены.
Ранние последователи, такие как Quiver (переходящий с Mintlify) и Neon (использующий add-mcp docs), уже оценили преимущества. Если вы ищете способ быстро запустить профессиональную документацию, которая будет работать быстро для людей и эффективно для AI-агентов, Blume — это инструмент, который стоит попробовать. Его открытая лицензия MIT и возможность выгрузки в чистый Astro-проект делают его безопасным выбором для долгосрочных проектов.
Рекомендуем начать с простой папки Markdown и команды npx blume init, чтобы оценить потенциал инструмента. Следите за обновлениями в GitHub-репозитории проекта, так как экосистема быстро развивается.
Источник: MarkTechPost ↗