Rspress 2.0 rilasciato: un nuovo aggiornamento focalizzato su esperienza e AI

Siamo lieti di annunciare il rilascio ufficiale di Rspress 2.0!

Rspress è un generatore di siti statici basato su Rsbuild, progettato come strumento di documentazione per sviluppatori. Dalla sua pubblicazione ufficiale nel 2023, Rspress 1.x ha accumulato 144 versioni e ha visto la partecipazione di 125 contributori nello sviluppo del progetto. Sempre più sviluppatori scelgono Rspress, sfruttando le sue funzionalità come prestazioni di compilazione efficienti, routing convenzionale e anteprima della libreria di componenti per costruire siti di documentazione belli e affidabili.

Basato sul feedback e sui suggerimenti della comunità, Rspress 2.0 ha fatto ulteriori progressi in termini di estetica del tema, AI-native, esperienza di sviluppo della documentazione, e utilizzo con Rslib.

Perché Rspress 2.0

Rspress 1.x ha già affrontato il problema delle prestazioni di compilazione del framework di documentazione, ma ci sono ancora alcune problematiche che influenzano l'esperienza centrale come strumento di sviluppo della documentazione. La versione 2.0 non si limita a perseguire prestazioni di compilazione, ma si concentra anche su altri aspetti dell'esperienza del sito di documentazione:

• Stile del tema: un tema predefinito più bello, con diverse modalità di personalizzazione del tema, risolvendo il problema della mancanza di API stabili nella personalizzazione dei temi in 1.x.
• AI-native: la documentazione non serve solo ai lettori umani, ma deve anche essere compresa e utilizzata meglio dagli agenti. Rspress ora include la generazione di llms.txt e la funzionalità SSG-MD derivata da SSG, generando contenuti di rendering Markdown di alta qualità per la lettura da parte degli agenti.
• Compilazione su richiesta, avvio istantaneo: abilitato per impostazione predefinita lazyCompilation, insieme alla funzionalità di preload delle risorse durante l'hover dei link, costruendo solo i file necessari quando si accede a specifici percorsi, permettendo un avvio istantaneo indipendentemente dalle dimensioni del progetto.
• Evidenziazione del codice Shiki: integrazione predefinita di Shiki, completando l'evidenziazione della sintassi durante la costruzione, supportando il cambio di tema e l'estensione del transformer, come @rspress/plugin-twoslash, offrendo effetti di visualizzazione dei blocchi di codice più ricchi.
• Esperienza di sviluppo della documentazione: ottimizzazione di file come nav.json, meta.json con HMR e nuova json schema per suggerimenti di codice nell'IDE; verifica dei link rotti abilitata per impostazione predefinita; nuova sintassi per blocchi di codice file, supportando il riferimento a file esterni; @rspress/plugin-preview e @rspress/plugin-playground possono essere utilizzati contemporaneamente, ecc.
• Integrazione Rslib: ora è possibile scegliere Rspress come strumento di documentazione quando si utilizza create-rslib per creare progetti di librerie di componenti, costruendo rapidamente siti di documentazione per componenti.

Nuove funzionalità 2.0

Nuovo tema

Il tema predefinito 2.0 ha subito un aggiornamento sistematico, progettato dal designer del team @Zovn Wei, con un notevole miglioramento nell'estetica visiva e nell'esperienza di lettura, e ogni componente può essere sostituito in modo indipendente, offrendo un'alta personalizzabilità.

Personalizzazione del tema

Secondo il grado di personalizzazione, ci sono quattro modalità di personalizzazione del tema: variabili CSS, nomi di classi BEM, sovrascrittura di esportazioni ESM, e espulsione dei componenti.- Variabili CSS: Il nuovo tema espone più variabili CSS, sovrascrivendo i colori del tema, gli stili dei blocchi di codice, della homepage, ecc. Puoi visualizzare e regolare interattivamente tutte le variabili CSS nella pagina delle variabili CSS e, una volta trovata la configurazione soddisfacente, copiarla direttamente nel progetto per l'uso.

• Nomi di classe BEM: I componenti integrati ora seguono tutti la convenzione di denominazione BEM. Questa è una scelta molto Old School, ma è anche una decisione ben ponderata da parte nostra. Gli utenti possono regolare gli stili in modo preciso tramite i selettori CSS, rendendo la struttura HTML molto più chiara.
• Sovrascrittura dell'esportazione ESM: Se le modifiche CSS non soddisfano le esigenze di personalizzazione, è possibile effettuare una personalizzazione più profonda tramite JS. Utilizzando l'esportazione ESM in theme/index.tsx, puoi sovrascrivere qualsiasi componente integrato di Rspress.
• Eject dei componenti: Puoi utilizzare il nuovo comando rspress eject [component], che copierà il codice sorgente del componente specificato nella directory theme/components/, permettendoti di modificare liberamente quel codice, o addirittura di farlo modificare direttamente all'AI, per ottenere una personalizzazione profonda.

Tag della barra di navigazione e della barra laterale

Rspress 2.0 ha implementato il componente Tag, ora puoi utilizzare l'attributo tag nel frontmatter per annotare l'interfaccia utente nella barra laterale o nella barra di navigazione.

Supporto multilingue integrato

Nella versione 1.x, Rspress aveva solo testo in inglese integrato, e se volevi usare altre lingue come zh, dovevi configurare tutto il testo, risultando piuttosto complicato. Ora il tema 2.0 include testi tradotti in diverse lingue come zh, en, ja, ko, ru, ecc., e il sistema eseguirà automaticamente il "Tree Shaking" in base alla configurazione della lingua, impacchettando solo i testi e le lingue che utilizzi.

Supporto per llms.txt

Rspress ora integra la capacità di generare llms.txt nel core e ha implementato una nuova capacità SSG-MD (Static Site Generation to Markdown, generazione di siti statici in Markdown).

Nei framework frontend basati su React, spesso ci sono problemi nell'estrazione di informazioni statiche, e Rspress affronta la stessa sfida. Rspress consente agli utenti di migliorare l'espressività dei documenti tramite frammenti MDX, componenti React, Hooks e caratteristiche di routing TSX. Tuttavia, questi contenuti dinamici affrontano i seguenti problemi quando vengono convertiti in testo Markdown:

• Fornire direttamente l'input MDX all'AI comporterà una grande quantità di rumore sintattico di codice e perderà il contenuto dei componenti React.
• Convertire HTML in Markdown spesso non produce buoni risultati, e la qualità delle informazioni è difficile da garantire.

Per risolvere questo problema, Rspress 2.0 introduce la funzionalità SSG-MD. Questa è una nuova funzionalità che è simile alla generazione di siti statici (SSG), ma la differenza è che renderizza le tue pagine come file Markdown, anziché come file HTML, generando file correlati llms.txt e llms-full.txt.

Evidenziazione del codice nei blocchi di codice durante la compilazione ShikiRspress 2.0 utilizza Shiki per l'evidenziazione del codice per impostazione predefinita. Rispetto alla soluzione di evidenziazione runtime prism di 1.x, Shiki completa il trattamento dell'evidenziazione in fase di compilazione.

• Supporta vari stili tematici, ad esempio nella pagina delle variabili CSS è possibile passare e visualizzare interattivamente diversi temi Shiki.
• Allo stesso tempo, Shiki consente anche di utilizzare transformer personalizzati per arricchire la scrittura, come twoslash, ecc.
• Importa i linguaggi di programmazione su richiesta, senza aumentare il sovraccarico runtime e la dimensione del pacchetto.
• Basato sulla sintassi di TextMate, fornisce un'evidenziazione della sintassi accurata e coerente con VS Code.

Miglioramenti delle prestazioni di costruzione

Rspress 2.0 è alimentato dalla versione di anteprima di Rsbuild e Rspack 2.0, e per impostazione predefinita ha attivato la compilazione su richiesta e la cache persistente.

Compilazione su richiesta

La compilazione dev.lazyCompilation è attivata per impostazione predefinita, quindi solo quando accedi a una certa pagina, quella pagina verrà compilata, migliorando notevolmente la velocità di avvio dello sviluppo, realizzando persino un avvio a freddo in millisecondi. Rspress ha anche implementato una strategia di preload per il routing, caricando in anticipo la pagina di routing di destinazione quando il mouse è sopra il link, combinando lazyCompilation per un'esperienza di sviluppo senza perdite.

Cache persistente

La versione 2.0 ha anche attivato per impostazione predefinita la cache persistente, riutilizzando i risultati della compilazione precedente durante l'avvio caldo, migliorando la velocità di costruzione del 30%-60%. Questo significa che dopo la prima esecuzione di rspress dev o rspress build, la velocità di avvio successiva sarà notevolmente migliorata.

Esperienza di sviluppo della documentazione

Controllo dei link interrotti attivato per impostazione predefinita

Rspress 2.0 attiva per impostazione predefinita la funzione di controllo dei link interrotti. Durante il processo di costruzione, verranno automaticamente rilevati i link non validi nella documentazione, aiutandoti a scoprirli e correggerli in tempo.

Blocchi di codice da file

Puoi utilizzare l'attributo file="./path/to/file" per fare riferimento a file esterni come contenuto del blocco di codice, mantenendo il codice di esempio in file separati.

Uso più flessibile di meta in preview

@rspress/plugin-preview ora utilizza l'attributo meta, rendendolo più flessibile e può anche essere combinato con i blocchi di codice da file.

Rslib & Rspress

Quando utilizzi create-rslib per creare un progetto, ora puoi scegliere lo strumento Rspress. Questo ti consente di costruire rapidamente un sito di documentazione per scrivere istruzioni per l'uso dei componenti, mostrare riferimenti API o visualizzare in tempo reale l'effetto dei componenti mentre sviluppi una libreria di componenti.

Altri plugin ufficiali di Rspress

Rspress 2.0 ha aggiunto diversi plugin ufficiali:

• @rspress/plugin-algolia: supporta la sostituzione della ricerca integrata di Rspress con Algolia DocSearch
• @rspress/plugin-twoslash: aggiunge suggerimenti di tipo ai blocchi di codice TypeScript
• @rspress/plugin-llms: fornisce la capacità di generare llms.txt per progetti che non supportano SSG e SSG-MD
• @rspress/plugin-sitemap: genera automaticamente file Sitemap per ottimizzare la SEO

Cambiamenti significativi

Migrazione da Rspress 1.x

Se sei un utente di un progetto 1.x, abbiamo preparato un documento di migrazione dettagliato per aiutarti ad aggiornare da 1.x a 2.0. Puoi utilizzare direttamente la funzione "Copia Markdown" nella pagina per inserirla nel tuo agente di codifica abituale (come Claude Code, ecc.) per completare la migrazione.### Node.js e requisiti di versione delle dipendenze upstream

Rspress 2.0 richiede Node.js versione 20+, React versione 18+.

Prossimi passi

Il rilascio di Rspress 2.0 è solo un nuovo punto di partenza. Dopo questo rilascio, Rspress continuerà a iterare:

• Promuovere l'integrazione ecologica: combinazione più profonda con Rslib, Rstest, per fornire un'esperienza di sviluppo integrata per progetti frontend e librerie di componenti.
• Esplorare un'integrazione più profonda tra AI e documentazione: come domande e risposte intelligenti, riassunti automatici, ecc.; migliorare SSG-MD per renderlo stabile e più facile da usare.

Inizia a usare o aggiorna a Rspress 2.0, per vivere un nuovo viaggio nello sviluppo della documentazione!

npm create rspress@latest