Blume: framework open-source da OpenAI transforma pasta Markdown em documentação pronta para IA

Hayden Bleasel, engenheiro da OpenAI, lançou o Blume, um framework open-source de documentação que transforma uma pasta de arquivos Markdown em um site de documentação profissional com zero configuração. A ferramenta foi publicada no npm como versão 1.0.3 e já está disponível sob licença MIT.

O que é o Blume?

Blume é uma ferramenta de linha de comando combinada com uma biblioteca de componentes React para documentação. Ele lê uma pasta com arquivos .md ou .mdx e gera um site de documentação completo, com navegação hierárquica, busca local, temas customizáveis e imagens Open Graph automáticas. A configuração é totalmente opcional e incremental: você adiciona um arquivo de cada vez, conforme precisa.

O código é um monorepo TypeScript e requer Node.js 22.12 ou superior. Funciona com Bun, pnpm, npm ou yarn. A própria documentação do Blume é construída com o Blume — um exemplo clássico de dogfooding.

Como funciona por dentro

O Blume gera e gerencia um projeto Astro oculto. O fluxo é o seguinte:

1. A CLI carrega o arquivo blume.config.ts e escaneia o conteúdo em um grafo de páginas
2. Escreve um projeto Astro completo no diretório .blume/
3. O Astro renderiza cada página através de uma única rota catch-all que importa os componentes do Blume, seus dados e suas personalizações
4. A cada execução, apenas arquivos modificados são reescritos, mantendo o hot reload rápido

O tema padrão não carrega JavaScript no lado do cliente, o que resulta em excelentes pontuações no Core Web Vitals. Quando você precisa de controle total, blume eject promove o runtime para um app Astro independente.

Primeiros passos

A inicialização é um comando único:

npx blume init

Depois, blume dev inicia o servidor de desenvolvimento com hot reload e blume build gera HTML estático com índice de busca local na pasta dist/. O arquivo de configuração é TypeScript puro com schema validado:

// blume.config.ts
import { defineConfig } from "blume";

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "docs" },
      { type: "notion", database: process.env.NOTION_DB },
    ],
  },
});

O CLI cobre o ciclo completo:

Pronto para IA por design

Além de leitores humanos, o Blume foi projetado para agentes de IA. Cada página retorna Markdown puro quando você adiciona .md à URL. Uma flag única gera llms.txt e llms-full.txt para consumo por LLMs. Cada página pode ser copiada como Markdown ou aberta diretamente no ChatGPT, Claude ou v0.

Há também um assistente Ask AI opcional que responde perguntas diretamente na página, usando o AI SDK da Vercel, OpenRouter, Inkeep ou qualquer endpoint compatível com OpenAI. E o ponto alto: o Blume pode hospedar um servidor MCP (Model Context Protocol):

claude mcp add --transport http your-docs https://docs.example.com/mcp

O servidor MCP expõe quatro ferramentas somente leitura: search_docs, get_page, list_pages e get_navigation. Isso significa que Claude Code, Cursor e VS Code podem consultar sua documentação diretamente durante a codificação.

Casos de uso

• API: adicione uma especificação OpenAPI ou AsyncAPI. O Blume renderiza referência interativa com schemas, autenticação e playground de requisições via Scalar
• Bibliotecas: aponte o Blume para seus GitHub Releases. Cada release gera um changelog automático com feed RSS
• Internacionalização: adicione arquivos traduzidos por locale. O Blume suporta 36 idiomas com roteamento por locale e layouts RTL
• Conteúdo misto: combine arquivos locais com MDX remoto, Notion ou Sanity. Todas as fontes renderizam pelos mesmos componentes

Comparativo

Pontos fortes e limitações

✅ Pontos fortes

• Zero configuração para começar: uma pasta de Markdown vira site completo em segundos
• Output estático sem JavaScript no cliente, favorecendo Core Web Vitals
• Superfícies de IA nativas: llms.txt, Markdown por página, servidor MCP e Ask AI
• Configuração type-safe (TypeScript) que pega erros antes do build
• Caminho de eject para app Astro independente reduz vendor lock-in

⚠️ Limitações

• Versão 1.0.3 é recente e o ecossistema ainda é jovem
• Requer Node.js 22.12+, o que pode ser uma barreira em ambientes legados
• Funcionalidades como Ask AI e MCP server precisam de um adapter server-side
• Menos integrações com terceiros que plataformas maduras como Mintlify
• Modelo self-hosted significa que você gerencia analytics e assistente por conta própria

Por que isso importa

O Blume chega em um momento em que a documentação técnica está sendo redesenhada para consumo por máquinas, não apenas por humanos. Com a ascensão de ferramentas como Cursor, Copilot e Claude Code, a capacidade de expor documentação via protocolos como MCP deixa de ser diferencial para se tornar requisito básico. O Blume é um dos primeiros frameworks a tratar LLMs como cidadãos de primeira classe na documentação, não como afterthought.

Early adopters incluem Quiver, que migrou do Mintlify, e a documentação add-mcp da Neon. O repositório está disponível no GitHub sob licença MIT.