Rspress 2.0 wydanie: nowa aktualizacja skoncentrowana na doświadczeniu i AI

Z radością ogłaszamy oficjalne wydanie Rspress 2.0!

Rspress to generator statycznych stron oparty na Rsbuild, stworzony jako narzędzie do dokumentacji dla deweloperów. Od momentu oficjalnego wydania w 2023 roku, Rspress 1.x przeszedł 144 iteracje i ma 125 współtwórców zaangażowanych w rozwój projektu. Coraz więcej deweloperów wybiera Rspress, korzystając z jego wydajności kompilacji, konwencjonalnego routingu i podglądu biblioteki komponentów, aby stworzyć estetyczne i niezawodne strony dokumentacyjne.

Na podstawie opinii i sugestii społeczności, Rspress 2.0 poszedł o krok dalej w zakresie estetyki motywów, AI-native, doświadczenia w tworzeniu dokumentacji oraz użycia z Rslib.

Dlaczego Rspress 2.0

Rspress 1.x rozwiązał problemy z wydajnością kompilacji w ramach frameworka stron dokumentacyjnych, ale wciąż istniały pewne problemy wpływające na kluczowe doświadczenie jako narzędzie do tworzenia dokumentacji. Wersja 2.0 nie tylko dąży do poprawy wydajności kompilacji, ale także koncentruje się na innych aspektach doświadczenia w tworzeniu stron dokumentacyjnych:

• Styl motywu: zestaw ładniejszego domyślnego motywu, z różnymi sposobami dostosowywania, rozwiązując problem braku stabilnego API w dostosowywaniu motywów w 1.x.
• AI-native: dokumenty nie tylko służą ludzkim czytelnikom, ale muszą być również lepiej rozumiane i wykorzystywane przez Agentów. Rspress teraz ma wbudowaną funkcję generowania llms.txt oraz SSG-MD pochodzącą z SSG, generującą wysokiej jakości treści renderowane w Markdown do odczytu przez Agentów.
• Kompilacja na żądanie, natychmiastowe uruchomienie: domyślnie włączona lazyCompilation, w połączeniu z funkcją preload zasobów podczas najeżdżania na linki, buduje wymagane pliki tylko podczas dostępu do określonych tras, co pozwala na natychmiastowe uruchomienie niezależnie od wielkości projektu.
• Podświetlanie kodu Shiki: domyślnie zintegrowane Shiki, które kończy podświetlanie składni podczas budowy, wspiera przełączanie motywów, rozszerzenia transformerów, takie jak @rspress/plugin-twoslash, oferując bogatsze efekty wyświetlania bloków kodu.
• Doświadczenie w tworzeniu dokumentacji: optymalizacja HMR dla plików nav.json, meta.json i dodanie schematu json do podpowiedzi kodu w IDE; domyślnie włączona funkcja sprawdzania martwych linków; nowa składnia bloków kodu dla plików, wspierająca odwołania do zewnętrznych plików; @rspress/plugin-preview i @rspress/plugin-playground wspierają jednoczesne użycie itp.
• Integracja Rslib: teraz można wybrać Rspress jako narzędzie do dokumentacji podczas tworzenia projektu biblioteki komponentów za pomocą create-rslib, szybko budując stronę dokumentacyjną komponentów.

Nowe funkcje 2.0

Nowy motyw

Domyślny motyw 2.0 przeszedł systematyczną aktualizację, zaprojektowaną przez zespół projektantów @Zovn Wei, z dużym wzrostem w zakresie efektów wizualnych i doświadczenia czytania, a każdy komponent może być niezależnie wymieniany, co zapewnia dużą elastyczność w dostosowywaniu.

Dostosowywanie motywu

W zależności od stopnia dostosowania, istnieją cztery sposoby dostosowywania motywu: zmienne CSS, klasy BEM, ponowne eksportowanie ESM oraz wyodrębnienie komponentów.- Zmienne CSS: Nowy motyw ujawnia więcej zmiennych CSS, które obejmują kolory motywu, style bloków kodu, strony głównej i inne. Możesz interaktywnie podglądać i dostosowywać wszystkie zmienne CSS na stronie zmiennych CSS, a po znalezieniu satysfakcjonującej konfiguracji możesz je bezpośrednio skopiować do swojego projektu.

• Nazewnictwo BEM: Wbudowane komponenty teraz korzystają z konwencji nazewnictwa BEM. To bardzo klasyczny wybór, ale także przemyślana decyzja. Użytkownicy mogą precyzyjnie dostosować style za pomocą selektorów CSS, a struktura HTML jest bardziej przejrzysta.
• Przekazywanie ESM: Jeśli zmiany w CSS nie spełniają wymagań dostosowawczych, można przeprowadzić głębsze dostosowanie za pomocą JS. W pliku theme/index.tsx wykorzystując ESM, można nadpisać dowolny wbudowany komponent Rspress.
• Eject komponentu: Możesz użyć nowego polecenia rspress eject [component], które skopiuje kod źródłowy określonego komponentu do katalogu theme/components/, gdzie możesz dowolnie modyfikować ten kod, a nawet zlecić AI jego modyfikację, aby osiągnąć głęboką personalizację.

Tag na pasku nawigacyjnym i bocznym

Rspress 2.0 wprowadza komponent Tag, który teraz pozwala na użycie atrybutu tag w frontmatter do oznaczania UI w pasku bocznym lub nawigacyjnym.

Wbudowane wsparcie dla wielu języków

W wersji 1.x Rspress miał wbudowany tylko angielski tekst, a korzystanie z innych języków, takich jak zh, wymagało konfiguracji wszystkich tekstów, co było dość uciążliwe. Teraz motyw 2.0 ma wbudowane tłumaczenia dla wielu języków, takich jak zh, en, ja, ko, ru, a system automatycznie przeprowadza "Tree Shaking" w zależności od konfiguracji językowej, pakując tylko używane teksty i języki.

Wsparcie dla llms.txt

Rspress teraz integruje zdolność generowania llms.txt w rdzeniu i wprowadza nową funkcjonalność SSG-MD (Static Site Generation to Markdown, generowanie statycznych stron do Markdown).

W oparciu o dynamicznie renderowane ramy front-endowe oparte na React, często występuje problem z trudnością w wydobywaniu statycznych informacji, a Rspress stoi przed tym samym wyzwaniem. Rspress pozwala użytkownikom na wzbogacenie dokumentów za pomocą fragmentów MDX, komponentów React, Hooks oraz dynamicznych cech TSX. Jednak te dynamiczne treści napotykają następujące problemy podczas konwersji na tekst Markdown:

• Bezpośrednie przekazanie MDX do AI zawiera dużą ilość szumów składniowych kodu i traci zawartość komponentów React.
• Konwersja HTML na Markdown często nie przynosi dobrych rezultatów, a jakość informacji jest trudna do zapewnienia.

Aby rozwiązać ten problem, Rspress 2.0 wprowadza funkcję SSG-MD. To nowa funkcjonalność, która jest podobna do generowania statycznych stron (SSG), ale różni się tym, że renderuje twoje strony jako pliki Markdown, a nie pliki HTML, generując pliki llms.txt i llms-full.txt.

Podświetlanie bloków kodu w czasie kompilacji ShikiRspress 2.0 domyślnie używa Shiki do podświetlania kodu. W porównaniu do rozwiązania podświetlania w czasie rzeczywistym prism 1.x, Shiki wykonuje przetwarzanie podświetlania w czasie kompilacji.

• Obsługuje różne style motywów, na przykład na stronie zmiennych CSS można interaktywnie przełączać i podglądać różne motywy Shiki.
• Shiki pozwala również na użycie niestandardowych transformerów do rozszerzenia możliwości pisania, takich jak twoslash itp.
• Wprowadza języki programowania na żądanie, nie zwiększając obciążenia w czasie wykonywania i rozmiaru pakietu.
• Oparte na składni TextMate zapewnia dokładne podświetlanie składni zgodne z VS Code.

Poprawa wydajności budowy

Rspress 2.0 jest napędzany przez Rsbuild i wersję podglądową Rspack 2.0, a domyślnie włączono kompilację na żądanie i trwałe pamięci podręczne.

Kompilacja na żądanie

Domyślnie włączono dev.lazyCompilation, co oznacza, że strona jest kompilowana tylko wtedy, gdy ją odwiedzisz, co znacznie zwiększa prędkość uruchamiania w trybie deweloperskim, a nawet osiąga poziom uruchamiania zimnego w milisekundach. Rspress wdrożył również strategię preload dla routingu, która wstępnie ładowała stronę docelową, gdy kursor znajduje się nad linkiem, w połączeniu z lazyCompilation, co zapewnia bezstratne doświadczenie deweloperskie.

Trwałe pamięci podręczne

2.0 domyślnie włącza również trwałe pamięci podręczne, ponownie wykorzystując wyniki ostatniej kompilacji w trybie gorącym, co zwiększa prędkość budowy o 30%-60%. Oznacza to, że po pierwszym uruchomieniu rspress dev lub rspress build, prędkość uruchamiania w kolejnych uruchomieniach będzie znacznie wyższa.

Doświadczenie rozwoju dokumentacji

Domyślnie włączone sprawdzanie martwych linków

Rspress 2.0 domyślnie włącza funkcję sprawdzania martwych linków. W trakcie budowy automatycznie wykrywa nieprawidłowe linki w dokumentacji, pomagając Ci szybko je zidentyfikować i naprawić.

Bloki kodu plików

Możesz użyć atrybutu file="./path/to/file", aby odwołać się do zewnętrznego pliku jako zawartości bloku kodu, utrzymując przykładowy kod w osobnym pliku.

bardziej elastyczne użycie meta w preview

@rspress/plugin-preview teraz korzysta z atrybutu meta, co czyni go bardziej elastycznym, a także można go używać w połączeniu z blokami kodu plików.

Rslib & Rspress

Podczas używania create-rslib do tworzenia projektu, teraz możesz wybrać narzędzie Rspress. Umożliwia to szybkie zbudowanie towarzyszącej strony dokumentacyjnej podczas rozwijania biblioteki komponentów, służącej do pisania instrukcji użycia komponentów, prezentacji referencji API lub podglądu efektów komponentów w czasie rzeczywistym.

Więcej oficjalnych wtyczek Rspress

Rspress 2.0 dodał kilka oficjalnych wtyczek:

• @rspress/plugin-algolia: umożliwia zastąpienie wbudowanej wyszukiwarki Rspress Algolia DocSearch
• @rspress/plugin-twoslash: dodaje podpowiedzi typów do bloków kodu TypeScript
• @rspress/plugin-llms: zapewnia możliwość generowania llms.txt dla projektów, które nie obsługują SSG i SSG-MD
• @rspress/plugin-sitemap: automatycznie generuje plik Sitemap, aby zoptymalizować SEO

Zmiany przełomowe

Migracja z Rspress 1.x

Jeśli jesteś użytkownikiem projektu 1.x, przygotowaliśmy szczegółową dokumentację migracyjną, aby pomóc Ci zaktualizować z 1.x do 2.0. Możesz bezpośrednio skorzystać z funkcji "Kopiuj Markdown" na stronie, aby wprowadzić ją do swojego ulubionego agenta kodowania (takiego jak Claude Code itp.) w celu zakończenia migracji.### Node.js i wymagania dotyczące wersji zależności

Rspress 2.0 wymaga wersji Node.js 20+ oraz wersji React 18+.

Następny krok

Wydanie Rspress 2.0 to tylko nowy punkt wyjścia. Po tym wydaniu Rspress będzie kontynuować iterację:

• Rozwój integracji ekosystemu: głębsza integracja z Rslib i Rstest, oferująca zintegrowane doświadczenie w zakresie rozwoju projektów front-endowych i bibliotek komponentów.
• Eksploracja głębszej integracji AI z dokumentacją: takie jak inteligentne pytania i odpowiedzi, automatyczne podsumowania itp.; doskonalenie SSG-MD, aby stało się stabilniejsze i łatwiejsze w użyciu.

Natychmiast użyj lub zaktualizuj do Rspress 2.0, aby doświadczyć nowej podróży w tworzeniu dokumentacji!

npm create rspress@latest