Rspress 2.0 vydání: Nové vylepšení zaměřené na zkušenosti a AI

Jsme rádi, že můžeme oznámit oficiální vydání Rspress 2.0!

Rspress je generátor statických stránek založený na Rsbuild, navržený jako nástroj pro dokumentaci pro vývojáře. Od svého oficiálního vydání v roce 2023, Rspress 1.x celkem iteroval 144 verzí, s 125 přispěvateli zapojenými do vývoje projektu. Čím dál více vývojářů si vybírá Rspress, aby s jeho pomocí vytvořili krásné a spolehlivé dokumentační stránky díky jeho efektivnímu kompilaci, konvenčnímu směrování a náhledu knihovny komponentů.

Na základě zpětné vazby a návrhů komunity, Rspress 2.0 udělal další krok v oblastech jako estetika tématu, AI-native, zkušenost s vývojem dokumentace, použití s Rslib a další.

Proč Rspress 2.0

Rspress 1.x již vyřešil problém s kompilací rámce dokumentační stránky, ale stále existují některé problémy, které ovlivňují základní zkušenost jako nástroje pro vývoj dokumentace. Verze 2.0 se nezaměřuje pouze na zlepšení kompilace, ale také se soustředí na další aspekty zkušenosti s dokumentačními stránkami:

• Styl tématu: Sada krásnějšího výchozího tématu, která nabízí různé způsoby přizpůsobení, čímž řeší problém s nedostatkem stabilního API pro přizpůsobení témat v 1.x.
• AI-native: Dokumenty nejen slouží lidským čtenářům, ale musí být také lépe pochopeny a využity Agenty. Rspress nyní obsahuje funkce generování llms.txt a SSG-MD odvozené z SSG, které generují vysoce kvalitní Markdown obsah pro čtení Agentem.
• Kompilace na vyžádání, okamžité spuštění: Ve výchozím nastavení je aktivována lazyCompilation, spolu s funkcí preload pro zdroje při najetí na odkazy, což znamená, že soubory potřebné pro konkrétní směrování jsou sestaveny pouze při přístupu, což umožňuje okamžité spuštění bez ohledu na velikost projektu.
• Shiki zvýraznění kódu: Ve výchozím nastavení integrované Shiki, které provádí zvýraznění syntaxe při sestavení, podporuje přepínání témat a rozšíření transformerů, jako je @rspress/plugin-twoslash, což přináší bohatší zobrazení bloků kódu.
• Zkušenost s vývojem dokumentace: Optimalizace HMR pro soubory jako nav.json, meta.json a nově přidaný json schema pro nápovědu kódu v IDE; ve výchozím nastavení je aktivována kontrola mrtvých odkazů; nová syntaxe pro bloky kódu, která podporuje citace externích souborů; @rspress/plugin-preview a @rspress/plugin-playground nyní podporují současné použití atd.
• Integrace Rslib: Nyní je možné při vytváření projektu knihovny komponent pomocí create-rslib zvolit Rspress jako nástroj pro dokumentaci a rychle vytvořit dokumentační stránky komponent.

Nové funkce 2.0

Nové téma

Výchozí téma 2.0 prošlo systémovým vylepšením, které navrhl týmový designér @Zovn Wei, přičemž došlo k výraznému zlepšení vizuálních efektů a čtenářské zkušenosti, a každý komponent může být nezávisle nahrazen, což zajišťuje vysokou míru přizpůsobitelnosti.

Přizpůsobení tématu

Podle úrovně přizpůsobení od nejnižší po nejvyšší existují čtyři způsoby přizpůsobení tématu: CSS proměnné, BEM názvy tříd, ESM opětovné exporty a eject komponent.- CSS proměnné: Nové téma odhalilo více CSS proměnných, které pokrývají styly pro barvy tématu, bloky kódu, domovskou stránku a další. Můžete interaktivně prohlížet a upravovat všechny CSS proměnné na stránce s CSS proměnnými a po nalezení uspokojivého nastavení je přímo zkopírovat do projektu.

• BEM názvy tříd: Vestavěné komponenty nyní používají BEM pojmenovací konvenci. To je velmi staromódní volba, ale také naše pečlivě promyšlené rozhodnutí. Uživatelé mohou přesně upravit styly pomocí CSS selektorů, struktura HTML je jasnější.
• ESM opětovný export přepsání: Pokud úpravy na CSS nevyhovují potřebám přizpůsobení, můžete provést hlubší přizpůsobení pomocí JS. V souboru theme/index.tsx můžete využít ESM opětovný export k přepsání jakékoli vestavěné komponenty Rspress.
• Eject komponenty: Můžete použít zcela nový příkaz rspress eject [component], který zkopíruje zdrojový kód určené komponenty do adresáře theme/components/, kde můžete tyto kódy volně upravovat, dokonce je můžete přímo předat AI k úpravě pro dosažení hlubokého přizpůsobení.

Navigační lišta, postranní lišta tag

Rspress 2.0 implementoval komponentu Tag, nyní můžete použít atribut tag ve frontmatter pro UI označení na postranní liště nebo navigační liště.

Vestavěná podpora více jazyků

Ve verzi 1.x měl Rspress vestavěný pouze anglický text, pokud jste chtěli použít jiný jazyk, například zh, museli jste konfigurovat veškerý text, což bylo poněkud složité. Nyní téma 2.0 obsahuje vestavěné překlady pro různé jazyky jako zh, en, ja, ko, ru atd., systém automaticky provede "Tree Shaking" na základě jazykové konfigurace a zabalí pouze texty a jazyky, které používáte.

llms.txt podpora

Rspress nyní integroval schopnost generování llms.txt do jádra a implementoval zcela novou schopnost SSG-MD (Static Site Generation to Markdown, generování statických stránek do Markdown).

V rámci front-endového rámce založeného na Reactu často existuje problém s obtížným extrahováním statických informací, Rspress čelí stejným výzvám. Rspress umožňuje uživatelům zlepšit expresivitu dokumentů pomocí MDX fragmentů, React komponent, Hooks a TSX routování. Ale tyto dynamické obsahy čelí při převodu na Markdown text následujícím problémům:

• Přímo předání MDX AI obsahuje spoustu syntaktického šumu a ztrácí obsah React komponent
• Převod HTML na Markdown často nedává dobré výsledky, kvalita informací je obtížně zajištěna

Aby se tento problém vyřešil, Rspress 2.0 zavedl funkci SSG-MD. Je to zcela nová funkce, která je podobná statickému generování stránek (SSG), ale liší se v tom, že vaše stránky renderuje jako Markdown soubory, nikoli HTML soubory, a generuje související soubory llms.txt a llms-full.txt.

Shiki kompilace pro zvýraznění bloků kóduRspress 2.0 ve výchozím nastavení používá Shiki pro zvýraznění kódu. Ve srovnání s runtime zvýrazňovacím řešením prism 1.x, Shiki provádí zvýraznění při kompilaci.

• Podporuje různé styly témat, například na stránce s CSS proměnnými můžete interaktivně přepínat a prohlížet různá Shiki témata.
• Shiki také umožňuje používat vlastní transformátory pro rozšíření psaní, například twoslash atd.
• Na vyžádání zavádí programovací jazyky, aniž by zvyšoval runtime náklady a velikost balíčku.
• Na základě syntaxe TextMate poskytuje přesné zvýraznění syntaxe, které je v souladu s VS Code.

Zlepšení výkonu sestavení

Rspress 2.0 je poháněn základními verzemi Rsbuild a Rspack 2.0 a ve výchozím nastavení má zapnutou kompilaci na vyžádání a trvalou cache.

Kompilace na vyžádání

Ve výchozím nastavení je zapnuta dev.lazyCompilation, což znamená, že stránka bude kompilována pouze tehdy, když na ni přistoupíte, což výrazně zrychluje spuštění vývoje a dokonce umožňuje studené spuštění v milisekundách. Rspress také implementuje strategii preload pro směrování, kdy se při najetí myší na odkaz předem načte cílová stránka směrování, což v kombinaci s lazyCompilation poskytuje bezproblémový vývojový zážitek.

Trvalá cache

Verze 2.0 také ve výchozím nastavení zapíná trvalou cache, která znovu využívá výsledky poslední kompilace během horkého spuštění, což zvyšuje rychlost sestavení o 30%-60%. To znamená, že po prvním spuštění rspress dev nebo rspress build se rychlost následného spuštění výrazně zvýší.

Zážitek z vývoje dokumentace

Ve výchozím nastavení zapnuta kontrola mrtvých odkazů

Rspress 2.0 má ve výchozím nastavení zapnutou funkci kontroly mrtvých odkazů. Během procesu sestavení automaticky detekuje neplatné odkazy v dokumentaci, což vám pomůže včas je odhalit a opravit.

Kódové bloky souborů

Můžete použít atribut file="./path/to/file" k odkazu na externí soubor jako obsah kódového bloku, což vám umožní udržovat příkladový kód v samostatném souboru.

Flexibilnější použití meta pro preview

@rspress/plugin-preview nyní používá meta atribut, což je flexibilnější a může být také kombinováno s kódovými bloky souborů.

Rslib & Rspress

Při používání create-rslib k vytvoření projektu nyní můžete zvolit nástroj Rspress. To vám umožní rychle vybudovat odpovídající dokumentační stránku při vývoji knihovny komponentů, která slouží k psaní pokynů pro používání komponentů, zobrazení referencí API nebo k živému náhledu efektu komponentů.

Další oficiální pluginy Rspress

Rspress 2.0 přidala několik oficiálních pluginů:

• @rspress/plugin-algolia: Podporuje nahrazení vestavěného vyhledávání Rspress za Algolia DocSearch
• @rspress/plugin-twoslash: Přidává typové nápovědy pro bloky kódu TypeScript
• @rspress/plugin-llms: Poskytuje schopnost generování llms.txt pro projekty, které nepodporují SSG a SSG-MD
• @rspress/plugin-sitemap: Automaticky generuje soubor Sitemap pro optimalizaci SEO

Změny, které mění pravidla hry

Migrace z Rspress 1.x

Pokud jste uživatel projektu 1.x, připravili jsme podrobnou migrační dokumentaci, která vám pomůže upgradovat z 1.x na 2.0. Můžete přímo použít funkci "Kopírovat Markdown" na stránce a zadat ji do vašeho oblíbeného kódovacího agenta (např. Claude Code atd.) pro dokončení migrace.### Node.js a požadavky na verze závislostí

Rspress 2.0 vyžaduje verzi Node.js 20+ a verzi React 18+.

Další kroky

Vydání Rspress 2.0 je pouze novým začátkem. Po tomto vydání bude Rspress pokračovat v iteraci:

• Pokrok v ekologické integraci: Hlubší spojení s Rslib a Rstest, poskytující integrovaný vývojový zážitek pro front-end projekty a projekty knihoven komponentů.
• Zkoumání hlubší integrace AI a dokumentace: Například inteligentní otázky a odpovědi, automatické shrnutí atd.; vylepšení SSG-MD, aby bylo stabilnější a snadněji použitelné.

Začněte používat nebo aktualizujte na Rspress 2.0 a zažijte novou cestu vývoje dokumentace!

npm create rspress@latest