Il team open source di Meta ha recentemente rilasciato Docusaurus 3.9, un aggiornamento chiave del suo popolare generatore di siti statici basato su React.
La sua nuova versione, annunciata il 25 settembre, ha introdotto una nuova funzionalità significativa: un assistente di ricerca basato sull’intelligenza artificiale.
Oltre alle nuove funzionalità, l’aggiornamento modernizza anche la tecnologia sottostante, richiedendo agli sviluppatori di utilizzare Node.js 20 e terminando il supporto per il vecchio Node.js 18.
Ricerca conversazionale basata sull’intelligenza artificiale con DocSearch v4
Per gli sviluppatori che gestiscono documentazione su larga scala, l’aggiunta straordinaria di Docusaurus 3.9 è il supporto completo per DocSearch v4 di Algolia.
L’aggiornamento introduce AskAI, una funzionalità che trasforma la barra di ricerca standard di un sito in un assistente conversazionale.
Invece di limitarsi ad abbinare parole chiave, lo strumento fornisce risposte sintetizzate, aiutando gli utenti a risolvere i problemi in modo più efficiente.
Secondo il team di Docusaurus, l’obiettivo è”consentirti di aggiungere un assistente di ricerca basato sull’intelligenza artificiale al tuo sito Docusaurus in grado di rispondere a domande in base a ciò che è contenuto nella tua documentazione con un’esperienza di conversazione.”
Il passaggio dal recupero di parole chiave alle risposte conversazionali segna un’importante evoluzione nell’esperienza utente per la documentazione tecnica.
L’implementazione di questa ricerca avanzata è attivabile, fornendo il controllo della squadra sulla transizione. I manutentori del progetto possono scegliere di rimanere su DocSearch v3 o eseguire l’aggiornamento in modo incrementale per sbloccare le nuove funzionalità di intelligenza artificiale.
Per coloro che sono pronti ad adottarlo, Algolia fornisce un punto di ingresso accessibile. La pagina dei prezzi ufficiali descrive in dettaglio un livello”Build”gratuito che include 10.000 richieste di ricerca al mese, rendendo la funzionalità utilizzabile per progetti open source e team più piccoli.
Tale integrazione riflette una tendenza più ampia del settore che prevede l’integrazione dell’intelligenza artificiale generativa direttamente nelle piattaforme di sviluppo per aumentare la produttività e ridurre l’attrito tra gli utenti.
Modernizzare le basi: Node.js 20 ora richiesto
In una mossa mirata a migliorare la sicurezza e le prestazioni, Docusaurus 3.9 aumenta i requisiti minimi di runtime a Node.js v20.0, abbandona ufficialmente il supporto per Node.js 18.
Poiché Node.js 18 ha raggiunto la fine del suo ciclo di vita ufficiale, non riceve più aggiornamenti di sicurezza, rendendo il suo uso continuato una potenziale vulnerabilità.
Il team di Docusaurus considera questo aggiornamento obbligatorio come un passaggio cruciale per mantenere una piattaforma sicura e stabile.
“Dropping End-of-Life versioni di Node.js su rilasci di versioni minori è una pratica comune nell’ecosistema Node.js, che ora approviamo e documentiamo ufficialmente nel nostro processo di rilascio.”
Sebbene questa decisione sia una best practice, richiede l’azione dei team di sviluppo. Il suo impatto più immediato è sulle pipeline CI/CD e sugli ambienti di sviluppo locale.
Un esempio pratico di ciò è apparso su GitHub, dove uno sviluppatore ha presentato un problema notando che gli esempi di documentazione ufficiale per GitHub Actions puntavano ancora al deprecato Nodo 18, che richiede un aggiornamento per funzionare correttamente.
I team dovranno controllare non solo i propri script di build, ma anche i propri Dockerfile e i gestori dell’ambiente locale per garantire una transizione fluida ed evitare errori di build.
Flessibilità migliorata per i siti di documentazione globale
Affrontando una sfida di lunga data per i siti multilingue, Docusaurus 3.9 introduce importanti miglioramenti all’internazionalizzazione (i18n) system.
Gli sviluppatori possono ora sovrascrivere le proprietà `baseUrl` e `url` per ogni locale individualmente utilizzando il nuovo campo `i18n.localeConfigs[locale]`.
Fornisce il controllo granulare necessario per distribuzioni complesse e multidominio, ad esempio, ospitando documenti inglesi su”docs.example.com` e documenti francesi su `docs.example.fr`, garantendo al contempo che tutti i metadati e i collegamenti vengano risolti correttamente.
Ulteriori ottimizzazioni di i18n includono un nuovo flag `translate`, che ora è disabilitato per impostazione predefinita per i siti senza traduzioni, portando a tempi di creazione più rapidi evitando letture non necessarie del file system.
Inoltre, un nuovo attributo `key` può essere assegnato agli elementi della barra laterale. L’aggiunta di questa chiave impedisce le chiavi di traduzione entrano in conflitto quando più categorie condividono la stessa etichetta, come”API”, garantendo che ogni istanza possa essere tradotta in modo univoco in base al suo contesto all’interno della struttura della documentazione.
Miglioramenti chiave per diagrammi, prestazioni ed esperienza dello sviluppatore
Oltre alle funzionalità principali, Docusaurus 3.9 racchiude una serie di altri preziosi miglioramenti.
Tra questi c’è il supporto per l’algoritmo di layout Sirena ELK. Sirena è uno strumento popolare per creare diagrammi dal testo e il suo motore di layout ELK fornisce funzionalità di rendering più sofisticate, particolarmente utili per architetture di sistema grandi o complesse diagrammi.
Le prestazioni migliorano anche con l’aggiornamento a Rspack 1.5, che sfrutta nuove opzioni di configurazione per accelerare i tempi di creazione di Docusaurus. Build più veloci si traducono direttamente in una maggiore produttività degli sviluppatori, in particolare nei progetti di grandi dimensioni.
Altre modifiche degne di nota includono nuovi hook per la gestione dei collegamenti Markdown interrotti, la possibilità di disabilitare il rendering delle emoji e una migliore stabilità visiva quando si passa da una modalità colore all’altra.
Questi perfezionamenti collettivi consolidano la posizione di Docusaurus come piattaforma solida, performante e flessibile per la creazione di siti Web di documentazione moderni.
