Hayden Bleasel, un esperto sviluppatore da OpenAI, ha lanciato Blume, un framework open-source di documentazione. Blume funziona in modo semplice: basta caricare Markdown nella cartella desiderata, ed ecco realizzato un sito di documentazione professionale. Nessun codice extra necessario, e non è mai necessario aggiungerne manutenzione. Il progetto è rilasciato con una licenza MIT e open-source.

Che Cos'è Blume?

Blume è strumento da riga di comando abbinato ad una libreria di componenti per la documentazione. Legge un insieme di file Markdown o MDX da una determinata directory. Da quel contenuto genera in automatico un sito di documentazione pronti per l’uso con navigazione, ricerca, temi e Open Graph. Tutte le configurazioni, invece, seguono una logica opzionale e flessibile, aggiungendole file solo quando necessario.

Il codice è scritto in TypeScript all'interno di un monorepo, con il pacchetto principale disponibile in packages/blume. La documentazione generata da Blume si trova sotto apps/docs, e il sistema richiede un interprete Node.js versione 22.12 o successiva. L’esecuzione è compatibile con diversi gestori di pacchetti come Bun, pnpm, npm o yarn.

Come Funziona Blume?

Al di là della sua semplicità visiva, Blume genera un progetto “nascosto” in Astro, un framework popolare per i siti statici. Partendo dall'esecuzione del comando blume.config.ts, il sistema scansiona il contenuto nella cartella e produce le componenti necessarie. Questo generatore produce un singolo percorso “catch-all route”, rendendo possibile il rendering di ogni pagina con la stessa logica. La pagina importa componenti generati, i dati e le modifiche personalizzate dallo sviluppatore.

Ad ogni esecuzione, .blume/ aggiorna selettivamente solo i file interessati, facilitando il processo di editing con riload veloce. Le pagine non richiedono JavaScript e sono in grado di rispettare automaticamente gli standard Core Web Vitals. Inoltre, quando il controllo completo sull'app è richiesto, blume eject permette di promuovere il runtime in un'app standalone.

Avvio In Sede

Configurare Blume inizialmente richiede esclusivamente un comando:

Copy Code
npx blume init

Al successivo comando blume dev, parte direttamente il server di sviluppo, e blume build genera la versione finale come HTML statico insieme a un indice di ricerca. Il file di configurazione utilizzato è TypeScript, con validazioni integrate.

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

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

Le configurazioni sono verificate da editor in base ai tipi definiti, rendendo visibili eventuali errori prima della generazione del codice finale. Il CLI di Blume offre comandi completi per il ciclo di vita delle app:

blume init scaffolding di un progetto

blume dev esecuzione server sviluppo con riload

blume build genera HTML statico

blume add installa componenti registrati

blume sync aggiorna contenuti remoti

blume eject crea app standalone

blume validate verifica link

blume doctor diagnosi contenuti

Preparazione per L’Intelligenza Artificiale

Blume va al di là dei semplici lettori umani, integrando funzionalità pensate anche per gli agenti AI. Aggiungendo “.md” a un URL, l’app permette l’accesso al contenuto Markdown grezzo. Il flag llms.txt e llms-full.txt vengono generati automaticamente per ogni pagina e supportano l’interazione con agenti esterni. In pagina, un opzionale AI chatbot può essere installato, funzionante con il Vercel AI Gateway o endpoint OpenAI compatibili.

Puoi anche hostare un server MCP (Model Context Protocol) direttamente con Blume, abilitando l’accesso diretto a documentazioni in strumenti AI avanzati.

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

Il server esponendo quattro strumenti di sola lettura: searchdocs, getpage, listpages, getnavigation.

Esempi D’Uso

Le funzionalità di Blume si adattano a diversi scopi, ad esempio:

Per un API, carica la specifica OpenAPI con un render interattivo, playground e schema visibili.

Per una libreria, puntare a GitHub Releases e generare una timeline con aggiornamenti ed un feed RSS.

Per un pubblico globale, aggiungi documentazioni tradotte per ogni lingua supportata.

Combina locali e remote content sources per un rendering uniforme.

Riepilogo Caratteristiche

Blume presenta queste funzionalità fondamentali:

Zero-config, basta caricare markdown in una cartella.

Supporta automaticamente SEO e strumenti AEO.

30+ componenti inclusi.

Supporto avanzato su Astro e Vite.

Licenza MIT disponibile gratuitamente.

Confronto Con Framework Simili

Ecco una tabella comparativa tra Blume, Mintlify, Docusaurus e Astro Starlight:

Dimensione	Blume	Mintlify	Docusaurus	Astro Starlight
Tipo	CLI e framework open-source	Piattaforma hosted	SSG open-source	Tema Astro
Licenza	MIT, gratuito	Proprietario; tier a pagamento	MIT, gratuito	MIT, gratuito
Configurazione	Markdown senza setup	Configurazione orientata	React config, scaffold	Progetto Astro + tema
Strumenti	Hidden Astro + Vite	No;	React	Astro
JS Core	Statico HTML	—	Runtime React	Minimo (isole)
llms.txt	Flag integrato	Plugin community	—	—

Punti Forti E Debolezza

Lire l'article original →

← Retour aux actualités