Rspress 2.0 vydanie: Nové vylepšenia zamerané na skúsenosti a AI
Rspress 2.0 vydanie: Nové vylepšenia zamerané na skúsenosti a AI
S radosťou oznamujeme oficiálne vydanie Rspress 2.0!
Rspress je statický generátor stránok založený na Rsbuild, navrhnutý ako nástroj pre dokumentáciu pre vývojárov. Od svojho oficiálneho vydania v roku 2023, Rspress 1.x prešiel 144 iteráciami a na projekte sa podieľalo 125 prispievateľov. Čoraz viac vývojárov si vyberá Rspress, aby pomocou jeho efektívneho výkonu kompilácie, konvenčného smerovania a náhľadu knižnice komponentov vytvorili krásne a spoľahlivé dokumentačné stránky.
Na základe spätnej väzby a návrhov komunity, Rspress 2.0 posunul ďalej v oblasti atraktívnosti tém, AI-native, skúsenosti s vývojom dokumentácie a používania s Rslib.
Prečo Rspress 2.0
Rspress 1.x už vyriešil problémy s výkonom kompilácie rámca dokumentačných stránok, ale stále existujú niektoré problémy, ktoré ovplyvňujú základnú skúsenosť ako nástroja na vývoj dokumentácie. Verzia 2.0 sa nezameriava len na výkon kompilácie, ale aj na iné aspekty skúsenosti s dokumentačnými stránkami:
- Štýl témy: Sada krajšej predvolenej témy a rôzne spôsoby prispôsobenia témy, ktoré riešia problém 1.x s nedostatkom stabilného API pre prispôsobenie tém.
- AI-native: Dokumenty nielen slúžia ľudským čitateľom, ale musia byť aj lepšie pochopené a používané agentmi. Rspress teraz obsahuje funkciu generovania llms.txt a SSG-MD odvodenú z SSG, ktorá generuje kvalitný obsah Markdown na čítanie agentmi.
- Kompilácia na požiadanie, okamžité spustenie: Predvolene je povolená lazyCompilation, spolu s funkciou preload pre zdroje pri hoveri na odkazy, ktorá vytvára potrebné súbory len pri prístupe na konkrétne trasy, čo umožňuje okamžité spustenie bez ohľadu na veľkosť projektu.
- Shiki zvýraznenie kódu: Predvolene integrované Shiki, ktoré dokončuje zvýraznenie syntaxe pri kompilácii, podporuje prepínanie tém, rozšírenia transformerov, ako napríklad @rspress/plugin-twoslash, čo prináša bohatšie zobrazenie blokov kódu.
- Skúsenosť s vývojom dokumentácie: Optimalizácia HMR pre súbory nav.json, meta.json a pridanie json schémy pre kódové nápovedy v IDE; predvolene zapnutá funkcia kontroly nefunkčných odkazov; pridaná syntax pre bloky kódu súborov, ktorá podporuje citácie externých súborov; @rspress/plugin-preview a @rspress/plugin-playground podporujú súčasné používanie atď.
- Integrácia Rslib: Teraz je možné pri vytváraní projektu knižnice komponentov pomocou create-rslib zvoliť Rspress ako nástroj na dokumentáciu a rýchlo vytvoriť dokumentačné stránky komponentov.
Nové funkcie 2.0
Úplne nová téma
Predvolená téma 2.0 prešla systémovým vylepšením, ktoré navrhol tímový dizajnér @Zovn Wei, pričom vizuálny efekt a čitateľská skúsenosť sa výrazne zlepšili a každý komponent je možné nezávisle nahradiť, čo poskytuje vysokú úroveň prispôsobiteľnosti.
Prispôsobenie témy
Podľa úrovne prispôsobenia od najnižšej po najvyššiu existujú štyri spôsoby prispôsobenia témy: CSS premenné, BEM názvy tried, ESM opätovné exportovanie a eject komponentov.- CSS premenné: Nová téma odhaľuje viac CSS premenných, ktoré pokrývajú témy farieb, štýly kódových blokov, domovskej stránky a ďalšie. Môžete interaktívne prezerať a upravovať všetky CSS premenné na stránke CSS premenných a po nájdení uspokojivého nastavenia ich priamo skopírovať do projektu.
- BEM názvy tried: Vstavané komponenty teraz používajú BEM názvovú konvenciu. Toto je veľmi staromódna voľba, ale je to aj naše dôkladne premyslené rozhodnutie. Používatelia môžu presne upravovať štýly pomocou CSS selektorov, HTML štruktúra je jasnejšia.
- ESM opätovný export: Ak úpravy na CSS nespĺňajú prispôsobené požiadavky, môžete vykonať hlbšie prispôsobenie pomocou JS. V súbore theme/index.tsx môžete využiť ESM opätovný export na prepisovanie akéhokoľvek vstavaného komponentu Rspress.
- Eject komponentu: Môžete použiť úplne nový príkaz rspress eject [component], ktorý skopíruje zdrojový kód zvoleného komponentu do adresára theme/components/. Tieto kódy môžete slobodne upravovať, dokonca ich priamo zveriť AI na úpravu, aby ste dosiahli hlboké prispôsobenie.
Navigačný panel, bočný panel tag
Rspress 2.0 implementoval Tag komponent, teraz môžete použiť atribút tag vo frontmatter na UI označenie v bočnom alebo navigačnom paneli.
Vstavaná podpora viacerých jazykov
V verzii 1.x Rspress obsahoval iba anglický text, ak ste chceli použiť iný jazyk, napríklad zh, museli ste nakonfigurovať všetok text, čo bolo dosť zložité. Teraz téma 2.0 obsahuje preklady textov v mnohých jazykoch ako zh, en, ja, ko, ru a systém automaticky vykonáva "Tree Shaking" na základe jazykovej konfigurácie, balí iba texty a jazyky, ktoré používate.
llms.txt podpora
Rspress teraz integruje schopnosť generovať llms.txt do core a implementuje úplne novú schopnosť SSG-MD (Static Site Generation to Markdown, generovanie statických stránok do Markdown).
V predných rámcoch založených na dynamickom renderovaní Reactu často existuje problém s ťažkým extrahovaním statických informácií, Rspress čelí rovnakým výzvam. Rspress umožňuje používateľom zlepšiť vyjadrovaciu schopnosť dokumentov pomocou MDX fragmentov, React komponentov, Hooks a TSX routingu a ďalších dynamických funkcií. Ale tieto dynamické obsahy čelí pri konverzii na Markdown text nasledujúcim problémom:
- Priame poskytnutie MDX AI obsahuje množstvo kódových syntaktických šumov a stráca obsah React komponentov
- Previesť HTML na Markdown často nedáva dobré výsledky, kvalita informácií je ťažko zaručená
Aby sa tento problém vyriešil, Rspress 2.0 zavádza funkciu SSG-MD. Toto je úplne nová funkcia, ktorá je podobná generovaniu statických stránok (SSG), ale líši sa v tom, že vaše stránky sa renderujú ako Markdown súbory, nie HTML súbory, a generujú súvisiace súbory llms.txt a llms-full.txt.
Shiki kompilácia a zvýraznenie kódových blokovRspress 2.0 predvolene používa Shiki na zvýraznenie kódu. V porovnaní s 1.x riešením zvýraznenia kódu prism, Shiki dokončuje zvýraznenie počas kompilácie.
- Podporuje rôzne témy, napríklad na stránke s CSS premennými môžete interaktívne prepínať a prezerať rôzne témy Shiki.
- Zároveň Shiki umožňuje používať vlastné transformátory na rozšírenie písania, ako napríklad twoslash a podobne.
- Na požiadanie zavádza programovacie jazyky, bez zvyšovania runtime nákladov a veľkosti balíka.
- Na základe syntaxe TextMate dosahuje presné zvýraznenie syntaxe, ktoré je v súlade s VS Code.
Zlepšenie výkonu kompilácie
Rspress 2.0 je poháňaný Rsbuild a Rspack 2.0 preview verziou, pričom predvolene zapína kompiláciu na požiadanie a trvalé cache.
Kompilácia na požiadanie
Predvolene je zapnuté dev.lazyCompilation, iba keď navštívite určitú stránku, táto stránka bude kompilovaná, čo výrazne zvyšuje rýchlosť spustenia vývoja, dokonca dosahuje studené spustenie na úrovni milisekúnd. Rspress zároveň implementoval stratégiu preload pre smerovanie, keď sa kurzor myši nachádza nad odkazom, predbežne sa načíta cieľová stránka smerovania, v kombinácii s lazyCompilation poskytuje bezstratový vývojový zážitok.
Trvalé cache
2.0 predvolene zapína trvalé cache, ktoré znovu využíva výsledky poslednej kompilácie v horúcom spustení, čo zvyšuje rýchlosť kompilácie o 30%-60%. To znamená, že po prvom spustení rspress dev alebo rspress build sa rýchlosť následného spustenia výrazne zvýši.
Vývojový zážitok dokumentácie
Predvolene zapnutá kontrola nefunkčných odkazov
Rspress 2.0 predvolene zapína funkciu kontroly nefunkčných odkazov. Počas kompilácie automaticky kontroluje neplatné odkazy v dokumente, čo vám pomôže včas ich odhaliť a opraviť.
Kódové bloky súborov
Môžete použiť atribút file="./path/to/file" na odkazy na externé súbory ako obsah kódového bloku, pričom príkladový kód udržiavate v samostatnom súbore.
flexibilnejšie použitie meta v preview
@rspress/plugin-preview teraz používa meta atribút, čo je flexibilnejšie a môže sa kombinovať s kódovými blokmi súborov.
Rslib & Rspress
Pri použití create-rslib na vytvorenie projektu teraz môžete zvoliť nástroj Rspress. To vám umožní rýchlo postaviť sprievodnú dokumentačnú stránku na písanie pokynov na používanie komponentov, zobrazenie referencií API alebo živé náhľady efektov komponentov.
Viac oficiálnych pluginov Rspress
Rspress 2.0 pridalo niekoľko oficiálnych pluginov:
- @rspress/plugin-algolia: podporuje nahradenie vstavaného vyhľadávania Rspress za Algolia DocSearch
- @rspress/plugin-twoslash: pridáva typové nápovedy pre kódové bloky TypeScript
- @rspress/plugin-llms: poskytuje schopnosť generovať llms.txt pre projekty, ktoré nepodporujú SSG a SSG-MD
- @rspress/plugin-sitemap: automaticky generuje súbor Sitemap na optimalizáciu SEO
Zmeny, ktoré narušujú kompatibilitu
Migrácia z Rspress 1.x
Ak ste používateľom projektu 1.x, pripravili sme podrobnú migračnú dokumentáciu, ktorá vám pomôže prejsť z 1.x na 2.0. Môžete priamo použiť funkciu "Kopírovať Markdown" na stránke a zadať ju svojmu obvyklému kódovému agentovi (ako Claude Code a podobne) na dokončenie migrácie.### Node.js a požiadavky na verziu závislostí
Rspress 2.0 vyžaduje verziu Node.js 20+ a verziu React 18+.
Ďalší krok
Uvoľnenie Rspress 2.0 je len nový začiatok. Po tomto uvoľnení bude Rspress pokračovať v iterácii:
- Pokrok v ekologickej integrácii: Hlbšia integrácia s Rslib a Rstest, poskytujúca integrovaný vývojový zážitok pre front-end projekty a projekty knižnice komponentov.
- Preskúmanie hlbšej integrácie AI a dokumentácie: Ako inteligentné otázky a odpovede, automatické zhrnutia atď.; vylepšiť SSG-MD, aby bol stabilnejší a jednoduchšie použiteľný.
npm create rspress@latest
