Rspress 2.0 Release: Een nieuwe upgrade gericht op ervaring en AI

We zijn verheugd om de officiële release van Rspress 2.0 aan te kondigen!

Rspress is een statische site-generator gebaseerd op Rsbuild, speciaal ontworpen als documentatietool voor ontwikkelaars. Sinds de officiële release in 2023 heeft Rspress 1.x in totaal 144 versies doorlopen, met 125 bijdragers die hebben bijgedragen aan de ontwikkeling van het project. Steeds meer ontwikkelaars kiezen voor Rspress, dankzij de efficiënte compilatieprestaties, conventionele routering en componentbibliotheekvoorbeelden, waarmee ze mooie en betrouwbare documentatiesites kunnen opzetten.

Gebaseerd op feedback en suggesties van de gemeenschap, heeft Rspress 2.0 verdere verbeteringen aangebracht op het gebied van thema esthetiek, AI-native, documentontwikkelingservaring, en gebruik in combinatie met Rslib.

Waarom Rspress 2.0

Rspress 1.x heeft al de problemen met de compilatieprestaties van documentatiesites opgelost, maar er zijn nog steeds enkele problemen die de kernervaring als documentontwikkelingshulpmiddel beïnvloeden. Versie 2.0 richt zich niet alleen op het verbeteren van de compilatieprestaties, maar ook op andere aspecten van de documentatiesite-ervaring:

• Thema stijl: Een mooier standaardthema en verschillende manieren om thema's aan te passen, waarmee het probleem van de instabiliteit van de API voor thema-aanpassing in 1.x wordt opgelost.
• AI-native: Documenten moeten niet alleen voor menselijke lezers dienen, maar ook beter begrepen en gebruikt worden door Agents. Rspress heeft nu ingebouwde functies voor het genereren van llms.txt en SSG-MD, die hoogwaardige Markdown-renderinhoud genereren voor Agents om te lezen.
• On-demand compilatie, onmiddellijke opstart: Standaard ingeschakeld lazyCompilation, samen met de preload-functie voor bronnen bij het hoveren over links, bouwt alleen de benodigde bestanden bij toegang tot specifieke routes, zodat ongeacht de grootte van het project, dev onmiddellijk kan opstarten.
• Shiki code-highlight: Standaard geïntegreerd Shiki, die syntax-highlighting tijdens de bouw voltooit, ondersteunt thema-wisseling en transformer-uitbreidingen, zoals @rspress/plugin-twoslash, wat zorgt voor een rijkere weergave van codeblokken.
• Documentontwikkelingservaring: Optimalisatie van HMR voor bestanden zoals nav.json, meta.json en nieuwe json-schema's voor code-aanbevelingen in IDE; standaard ingeschakeld functie voor het controleren van dode links; nieuwe syntaxis voor bestandscodeblokken, ondersteunt verwijzingen naar externe bestanden; @rspress/plugin-preview en @rspress/plugin-playground kunnen tegelijkertijd worden gebruikt, enz.
• Rslib integratie: Nu kan je bij het gebruik van create-rslib om componentbibliotheekprojecten te maken, Rspress kiezen als documentatietool, zodat je snel documentatiesites voor componenten kunt opzetten.

2.0 Nieuwe functies

Volledig nieuw thema

Het standaardthema van 2.0 heeft een systematische upgrade ondergaan, ontworpen door het teamontwerper @Zovn Wei, met aanzienlijke verbeteringen in visuele effecten en leeservaring, en elk component kan onafhankelijk worden vervangen, wat zorgt voor een hoge mate van aanpasbaarheid.

Thema aanpassing

Volgens de mate van aanpassing, van laag naar hoog, zijn er vier manieren om thema's aan te passen: CSS-variabelen, BEM-classnamen, ESM-herexportoverlap en component eject.- CSS-variabelen: Het nieuwe thema heeft meer CSS-variabelen blootgelegd, die de themakleur, codeblokken, startpagina en andere stijlen overschrijven. Je kunt alle CSS-variabelen interactief bekijken en aanpassen op de CSS-variabelenpagina, en zodra je een tevredenstellende configuratie hebt gevonden, kun je deze direct kopiëren voor gebruik in je project.

• BEM-classificaties: De ingebouwde componenten maken nu gebruik van de BEM-namingconventie. Dit is een zeer Old School keuze, maar ook een weloverwogen beslissing van onze kant. Gebruikers kunnen de stijlen nauwkeurig aanpassen met CSS-selectors, waardoor de HTML-structuur duidelijker wordt.
• ESM-heruitvoer overschrijving: Als de wijzigingen op CSS niet voldoen aan de aanpassingsbehoeften, kan er diepere aanpassing worden gedaan via JS. In theme/index.tsx kan je met ESM-heruitvoer elke ingebouwde component van Rspress overschrijven.
• Component eject: Je kunt de gloednieuwe rspress eject [component] opdracht gebruiken, deze opdracht kopieert de broncode van de opgegeven component naar de map theme/components/, waar je deze code vrij kunt aanpassen, of zelfs direct aan AI kunt geven voor aanpassing, om diepgaande aanpassingen te realiseren.

Navigatiebalk, zijbalk tag

Rspress 2.0 heeft de Tag-component geïmplementeerd, nu kun je de tag-eigenschap in frontmatter gebruiken om UI-markeringen in de zijbalk of navigatiebalk aan te brengen.

Ingebouwde meertalige ondersteuning

In versie 1.x had Rspress alleen Engelse tekst ingebouwd, als je andere talen zoals zh wilde gebruiken, moest je alle teksten configureren, wat vrij omslachtig was. Nu heeft het 2.0-thema ingebouwde vertalingen voor verschillende talen zoals zh, en, ja, ko, ru, enzovoort, en het systeem zal automatisch "Tree Shaking" uitvoeren op basis van de taalconfiguratie, alleen de teksten en talen bundelen die je gebruikt.

llms.txt ondersteuning

Rspress heeft nu de mogelijkheid om llms.txt te genereren geïntegreerd in de core, en heeft een nieuwe SSG-MD (Static Site Generation to Markdown, statische site Markdown-generatie) mogelijkheid gerealiseerd.

In front-end frameworks die dynamisch renderen op basis van React, is het vaak moeilijk om statische informatie te extraheren, en Rspress staat voor dezelfde uitdaging. Rspress staat gebruikers toe om de documentexpressiviteit te verbeteren via MDX-fragmenten, React-componenten, Hooks en TSX-routes. Maar deze dynamische inhoud kan de volgende problemen ondervinden bij conversie naar Markdown-tekst:

• Directe invoer van MDX aan AI bevat veel code-syntaxisruis en verliest de inhoud van React-componenten.
• Het omzetten van HTML naar Markdown levert vaak slechte resultaten op, en de informatiekwaliteit is moeilijk te waarborgen.

Om dit probleem op te lossen, introduceert Rspress 2.0 de SSG-MD-functie. Dit is een geheel nieuwe functie die lijkt op statische sitegeneratie (SSG), maar het verschil is dat het je pagina's rendert als Markdown-bestanden in plaats van HTML-bestanden, en genereert llms.txt en llms-full.txt gerelateerde bestanden.

Shiki compileertijd codeblok highlightsRspress 2.0 gebruikt standaard Shiki voor codehighlighting. In vergelijking met de runtime highlight-oplossing van 1.x's prism, voltooit Shiki de highlightverwerking tijdens de compilatie.

• Ondersteunt verschillende themastijlen, zoals interactief schakelen en previewen van verschillende Shiki-thema's op de CSS-variabelenpagina.
• Tegelijkertijd staat Shiki ook het gebruik van aangepaste transformers toe om de schrijfervaring te verrijken, zoals twoslash enz.
• Programmeertalen worden op aanvraag geïntroduceerd, zonder runtime overhead en pakketgrootte te verhogen.
• Gebaseerd op TextMate-syntax voor nauwkeurige syntaxhighlighting die consistent is met VS Code.

Prestatieverbeteringen bij bouwen

Rspress 2.0 is onder de motorkap aangedreven door Rsbuild en de previewversie van Rspack 2.0, en heeft standaard on-demand compilatie en persistente caching ingeschakeld.

On-demand compilatie

Standaard is dev.lazyCompilation ingeschakeld, waardoor een pagina alleen wordt gecompileerd wanneer je deze bezoekt, wat de opstarttijd van de ontwikkeling aanzienlijk versnelt, zelfs tot milliseconden voor koude starts. Rspress heeft ook een preload-strategie voor routing geïmplementeerd, waarbij de doelroutepagina vooraf wordt geladen wanneer de muis boven een link zweeft, in combinatie met lazyCompilation voor een naadloze ontwikkelervaring.

Persistente caching

2.0 heeft ook standaard persistente caching ingeschakeld, waarbij de resultaten van de vorige compilatie worden hergebruikt tijdens een warme start, wat de bouwsnelheid met 30%-60% verhoogt. Dit betekent dat na de eerste uitvoering van rspress dev of rspress build, de opstarttijd aanzienlijk zal verbeteren.

Documentontwikkelingservaring

Standaard ingeschakelde dode linkcontrole

Rspress 2.0 heeft standaard de functie voor dode linkcontrole ingeschakeld. Tijdens het bouwproces worden ongeldige links in de documentatie automatisch gedetecteerd, zodat je deze tijdig kunt ontdekken en repareren.

Bestandscodeblokken

Je kunt de file="./path/to/file"-eigenschap gebruiken om externe bestanden als inhoud van codeblokken te verwijzen, zodat voorbeeldcode in afzonderlijke bestanden kan worden onderhouden.

preview flexibeler meta gebruik

@rspress/plugin-preview gebruikt nu de meta-eigenschap, wat flexibeler is en ook kan worden gecombineerd met bestandscodeblokken.

Rslib & Rspress

Bij het gebruik van create-rslib om een project te maken, kun je nu de Rspress-tool kiezen. Dit stelt je in staat om snel een bijbehorende documentatiesite op te zetten terwijl je een componentenbibliotheek ontwikkelt, voor het schrijven van gebruiksaanwijzingen voor componenten, het tonen van API-referenties of het realtime previewen van componenteffecten.

Meer officiële Rspress-plug-ins

Rspress 2.0 heeft verschillende nieuwe officiële plug-ins toegevoegd:

• @rspress/plugin-algolia: vervangt de ingebouwde zoekfunctie van Rspress door Algolia DocSearch
• @rspress/plugin-twoslash: voegt typehinting toe aan TypeScript-codeblokken
• @rspress/plugin-llms: biedt llms.txt-generatiemogelijkheden voor projecten die SSG en SSG-MD niet ondersteunen
• @rspress/plugin-sitemap: genereert automatisch Sitemap-bestanden voor SEO-optimalisatie

Breaking changes

Migreren van Rspress 1.x

Als je een gebruiker bent van een 1.x-project, hebben we een gedetailleerde migratiedocumentatie voorbereid om je te helpen upgraden van 1.x naar 2.0. Je kunt de functie "Markdown kopiëren" op de pagina gebruiken om deze in te voeren bij je gebruikelijke coderingsagent (zoals Claude Code enz.) om de migratie te voltooien.[[HTMLPLACEHOLDER0]] [[HTMLPLACEHOLDER1]]

[[HTMLPLACEHOLDER2]] [[HTMLPLACEHOLDER3]] [[HTMLPLACEHOLDER4]] [[HTMLPLACEHOLDER5]]

[[HTMLPLACEHOLDER6]]