Rspress 2.0 lansering: En ny uppgradering för upplevelse och AI

Vi är glada att meddela den officiella lanseringen av Rspress 2.0!

Rspress är en statisk webbplatsgenerator baserad på Rsbuild, designad som ett dokumentationsverktyg för utvecklare. Sedan den officiella lanseringen 2023 har Rspress 1.x genomgått 144 versioner och totalt 125 bidragsgivare har deltagit i projektutvecklingen. Fler och fler utvecklare väljer Rspress för att bygga vackra och pålitliga dokumentationssajter med hjälp av dess effektiva kompilering, konventionell routing och komponentbiblioteksförhandsvisning.

Baserat på feedback och förslag från gemenskapen har Rspress 2.0 tagit ytterligare steg inom temats estetik, AI-native, dokumentationsutvecklingsupplevelse, och användning tillsammans med Rslib.

Varför Rspress 2.0

Rspress 1.x har redan löst problem med kompileringseffektivitet för dokumentationsramverket, men det finns fortfarande vissa problem som påverkar kärnupplevelsen som ett dokumentationsutvecklingsverktyg. Version 2.0 fokuserar inte bara på att förbättra kompileringseffektiviteten utan också på andra aspekter av dokumentationsupplevelsen:

• Temastil: En mer estetiskt tilltalande standardtema, med flera anpassningsalternativ, vilket löser problemet med bristande stabila API:er för temaanpassning i 1.x.
• AI-native: Dokumenten tjänar inte bara mänskliga läsare, utan behöver också förstås och användas bättre av agenter. Rspress har nu inbyggd funktionalitet för att generera llms.txt och SSG-MD från SSG, vilket skapar högkvalitativ Markdown-rendering för agenter att läsa.
• On-demand kompilering, omedelbar start: Standardaktiverad lazyCompilation, tillsammans med preload-funktionalitet för resurser vid länkhover, bygger endast nödvändiga filer när specifika rutter besöks, vilket möjliggör omedelbar start oavsett projektets storlek.
• Shiki kodsyntaxmarkering: Standardintegrerad Shiki, som slutför syntaxmarkering vid byggtid, stöder temabyten och transformerutvidgningar, som @rspress/plugin-twoslash, vilket ger en rikare visning av kodblock.
• Dokumentationsutvecklingsupplevelse: Optimering av HMR för filer som nav.json, meta.json och ny json-schema för kodtips i IDE; standardaktiverad död länk-kontrollfunktion; ny filkodblocksyntax som stöder referenser till externa filer; @rspress/plugin-preview och @rspress/plugin-playground kan användas samtidigt, etc.
• Rslib-integration: Nu kan du välja Rspress som dokumentationsverktyg när du använder create-rslib för att skapa komponentbiblioteksprojekt, vilket gör det snabbt att bygga dokumentationssajter för komponenter.

2.0 nya funktioner

Helt nytt tema

Det nya standardtemat i 2.0 har genomgått en systematisk uppgradering, designad av teamets designer @Zovn Wei, med betydande förbättringar i både visuell effekt och läsupplevelse, och varje komponent kan bytas ut oberoende, vilket ger hög anpassningsbarhet.

Temaanpassning

Baserat på anpassningsnivå från låg till hög finns det fyra sätt att anpassa temat: CSS-variabler, BEM-klassnamn, ESM-omexport och komponentutkast.- CSS variabler: Det nya temat har exponerat fler CSS variabler som täcker temafärger, kodblock, startsida och andra stilar. Du kan interaktivt förhandsgranska och justera alla CSS variabler på CSS variabler-sidan, och efter att ha hittat en tillfredsställande konfiguration kan du direkt kopiera den till ditt projekt för användning.

• BEM klassnamn: Inbyggda komponenter använder nu BEM namngivningsstandard. Detta är ett mycket gammaldags val, men också ett genomtänkt beslut från vår sida. Användare kan exakt justera stilar med CSS-väljare, och HTML-strukturen blir tydligare.
• ESM omexportering: Om ändringar i CSS inte kan uppfylla anpassningsbehoven kan du göra djupare anpassningar via JS. Genom att använda ESM omexportering i theme/index.tsx kan du överskrida vilken inbyggd komponent som helst i Rspress.
• Komponent eject: Du kan använda det helt nya rspress eject [component] kommandot, vilket kopierar källkoden för den angivna komponenten till theme/components/ katalogen. Du kan fritt modifiera dessa koder, eller till och med låta AI göra ändringar för att uppnå djup anpassning.

Navigeringsfält, sidofält taggar

Rspress 2.0 har implementerat Tag komponenten, och nu kan du använda tag-attributet i frontmatter för att göra UI-markeringar i sidofältet eller navigeringsfältet.

Inbyggt flerspråkigt stöd

I version 1.x hade Rspress endast inbyggd engelsk text. Om andra språk som zh användes, måste all text konfigureras, vilket var ganska krångligt. Nu har 2.0 temat inbyggda översättningstexter för flera språk som zh, en, ja, ko, ru, etc. Systemet kommer automatiskt att utföra "Tree Shaking" baserat på språkkonfigurationen, och endast paketera den text och språk du använder.

llms.txt stöd

Rspress har nu integrerat llms.txt genereringskapacitet i kärnan och implementerat en ny SSG-MD (Static Site Generation to Markdown, statisk webbplats Markdown-generering) kapabilitet.

I front-end ramverk som är baserade på React finns det ofta problem med att extrahera statisk information, och Rspress står inför samma utmaning. Rspress tillåter användare att förbättra dokumentens uttryckskraft genom MDX-fragment, React-komponenter, Hooks och TSX-rutter. Men dessa dynamiska innehåll står inför följande problem när de konverteras till Markdown-text:

• Att direkt ge MDX till AI kommer att innehålla mycket kodsyntaxbrus och förlora innehållet i React-komponenter.
• Att konvertera HTML till Markdown ger ofta dåliga resultat, och informationskvaliteten är svår att garantera.

För att lösa detta problem introducerar Rspress 2.0 SSG-MD-funktionen. Detta är en helt ny funktion som liknar statisk webbplatsgenerering (SSG), men skillnaden är att den renderar dina sidor som Markdown-filer istället för HTML-filer och genererar relaterade filer som llms.txt och llms-full.txt.

Shiki kompilering av kodblockshighlightingRspress 2.0 använder som standard Shiki för kodsyntaxmarkering. Jämfört med 1.x:s prism-baserade runtime-markering, utför Shiki syntaxmarkeringen vid kompilering.

• Stöder flera teman, till exempel kan du interaktivt växla och förhandsgranska olika Shiki-teman på CSS-variabelsidan.
• Samtidigt tillåter Shiki användning av anpassade transformatorer för att berika skrivandet, såsom twoslash med mera.
• Importerar programmeringsspråk vid behov, utan att öka runtime-kostnader och paketstorlek.
• Baserat på TextMate-syntax för att uppnå exakt syntaxmarkering som är konsekvent med VS Code.

Förbättrad byggprestanda

Rspress 2.0 drivs av Rsbuild och Rspack 2.0 förhandsversion, och har som standard aktiverat on-demand kompilering och persistent cache.

On-demand kompilering

Som standard är dev.lazyCompilation aktiverat, vilket innebär att en sida endast kommer att kompilera när du besöker den, vilket avsevärt ökar utvecklingsstarttiden och till och med möjliggör millisekundsnabb kallstart. Rspress implementerar också en preload-strategi för routing, där målsidan förladdas när muspekaren svävar över länken, vilket tillsammans med lazyCompilation ger en förlustfri utvecklingsupplevelse.

Persistent cache

2.0 har också som standard aktiverat persistent cache, vilket återanvänder resultatet från föregående kompilering under varmstart, vilket ökar bygghastigheten med 30%-60%. Detta innebär att efter den första körningen av rspress dev eller rspress build, kommer efterföljande starttider att öka avsevärt.

Dokumentationsutvecklingsupplevelse

Standardaktiverad dödlänkkontroll

Rspress 2.0 har som standard aktiverat dödlänkkontroll. Under byggprocessen kommer den automatiskt att upptäcka ogiltiga länkar i dokumentationen, vilket hjälper dig att snabbt upptäcka och åtgärda dem.

Filblock

Du kan använda attributet file="./path/to/file" för att referera till externa filer som innehåll i kodblock, vilket gör att du kan underhålla exempel på kod i separata filer.

preview mer flexibel meta-användning

@rspress/plugin-preview använder nu meta-attributet, vilket gör det mer flexibelt och kan också användas tillsammans med filblock.

Rslib & Rspress

När du använder create-rslib för att skapa projekt kan du nu välja Rspress-verktyget. Detta gör att du snabbt kan bygga en dokumentationssajt för att skriva användardokumentation för komponenter, visa API-referenser eller förhandsgranska komponenternas effekter i realtid.

Fler officiella Rspress-plugins

Rspress 2.0 har lagt till flera officiella plugins:

• @rspress/plugin-algolia: Stöder att ersätta Rspress inbyggda sökfunktion med Algolia DocSearch
• @rspress/plugin-twoslash: Lägger till typförslag för TypeScript-kodblock
• @rspress/plugin-llms: Ger llms.txt-genereringskapacitet för projekt som inte stöder SSG och SSG-MD
• @rspress/plugin-sitemap: Automatiskt generera Sitemap-filer för att optimera SEO

Brytande förändringar

Migrering från Rspress 1.x

Om du är användare av 1.x-projekt har vi förberett en detaljerad migrationsdokumentation för att hjälpa dig att uppgradera från 1.x till 2.0. Du kan direkt använda "Kopiera Markdown"-funktionen på sidan för att mata in den till din vanliga kodagent (som Claude Code med flera) för att slutföra migreringen.Rspress 2.0 kräver Node.js version 20+, React version 18+.\n\n## Nästa steg\n\nUtgivningen av Rspress 2.0 är bara en ny början. Efter denna utgivning kommer Rspress att fortsätta att iterera: \n\n- Främja ekointegration: Djupare integration med Rslib, Rstest för att erbjuda en integrerad utvecklingsupplevelse för frontend-projekt och komponentbiblioteksprojekt.\n- Utforska AI och djupare integration med dokument: Som intelligent frågesvar, automatisk sammanfattning etc.; Förbättra SSG-MD för att göra den stabilare och mer användarvänlig.\n\nBörja använda eller uppgradera till Rspress 2.0 för att uppleva en helt ny dokumentutvecklingsresa!\n\nnpm create rspress@latest