Rspress 2.0 veröffentlicht: Ein neues Upgrade für Erfahrung und KI

Wir freuen uns, die offizielle Veröffentlichung von Rspress 2.0 bekannt zu geben!

Rspress ist ein statischer Seiten-Generator, der auf Rsbuild basiert und speziell für Entwickler als Dokumentationswerkzeug entwickelt wurde. Seit der offiziellen Veröffentlichung im Jahr 2023 hat Rspress 1.x insgesamt 144 Versionen durchlaufen, an denen 125 Mitwirkende am Projekt gearbeitet haben. Immer mehr Entwickler entscheiden sich für Rspress, um mit seinen Funktionen wie effizienter Kompilierungsleistung, konventioneller Routenführung und Vorschau von Komponenten ansprechende und zuverlässige Dokumentationsseiten zu erstellen.

Basierend auf dem Feedback und den Vorschlägen der Community hat Rspress 2.0 in den Bereichen Ästhetik des Themas, KI-nativ, Dokumentationsentwicklungserfahrung und Verwendung mit Rslib weitere Fortschritte gemacht.

Warum Rspress 2.0

Rspress 1.x hat bereits das Problem der Kompilierungsleistung des Dokumentationsseiten-Frameworks gelöst, aber es gibt immer noch einige Probleme, die die Kern-Erfahrung als Dokumentationsentwicklungswerkzeug beeinträchtigen. Die Version 2.0 wird nicht nur die Kompilierungsleistung verbessern, sondern auch andere Aspekte der Dokumentationsseitenerfahrung in den Fokus rücken:

• Themenstil: Ein schöneres Standardthema, das verschiedene Möglichkeiten zur Anpassung bietet und das Problem der instabilen API bei der Themenanpassung in 1.x löst.
• KI-nativ: Dokumente dienen nicht nur menschlichen Lesern, sondern müssen auch von Agenten besser verstanden und genutzt werden. Rspress hat jetzt die Funktion zur Generierung von llms.txt und SSG-MD, die aus SSG abgeleitet ist, integriert, um qualitativ hochwertige Markdown-Inhalte für Agenten zu erstellen.
• On-Demand-Kompilierung, sofortiger Start: Standardmäßig wird lazyCompilation aktiviert, zusammen mit der Preload-Funktion für Ressourcen beim Hover über Links, wodurch nur die benötigten Dateien beim Zugriff auf bestimmte Routen erstellt werden, sodass unabhängig von der Projektgröße der dev auch sofort gestartet werden kann.
• Shiki-Code-Hervorhebung: Standardmäßig integriert Shiki, um Syntax-Hervorhebung während des Builds zu ermöglichen, unterstützt Themenwechsel und Transformer-Erweiterungen wie @rspress/plugin-twoslash, was zu einer reichhaltigeren Darstellung von Codeblöcken führt.
• Dokumentationsentwicklungserfahrung: Optimierung von HMR für Dateien wie nav.json, meta.json und Hinzufügung eines JSON-Schemas für Codehinweise in IDEs; standardmäßig aktivierte Überprüfung auf tote Links; neue Syntax für Datei-Codeblöcke, die das Referenzieren externer Dateien unterstützt; @rspress/plugin-preview und @rspress/plugin-playground können gleichzeitig verwendet werden usw.
• Rslib-Integration: Jetzt können Sie bei der Verwendung von create-rslib zur Erstellung von Komponentenbibliotheksprojekten Rspress als Dokumentationswerkzeug auswählen, um schnell Dokumentationsseiten für Komponenten zu erstellen.

Neue Funktionen in 2.0

Vollständig neues Thema

Das Standardthema von 2.0 hat ein systematisches Upgrade erfahren, das von unserem Designer-Team @Zovn Wei entworfen wurde. Es bietet erhebliche Verbesserungen in der visuellen Wirkung und im Leseerlebnis, und jede Komponente kann unabhängig ersetzt werden, was eine hohe Anpassungsfähigkeit ermöglicht.

Themenanpassung

Nach dem Grad der Anpassung von niedrig bis hoch gibt es vier Möglichkeiten zur Anpassung des Themas: CSS-Variablen, BEM-Klassennamen, ESM-Neuexport und Komponenten-Eject.- CSS-Variablen: Das neue Thema bietet mehr CSS-Variablen, die die Themenfarbe, Codeblöcke, Startseiten und andere Stile überschreiben. Du kannst alle CSS-Variablen interaktiv auf der CSS-Variablen-Seite anzeigen und anpassen und die zufriedenstellende Konfiguration direkt in dein Projekt kopieren.

• BEM-Klassennamen: Eingebaute Komponenten verwenden jetzt die BEM-Namenskonvention. Dies ist eine sehr Old-School-Wahl, aber auch eine wohlüberlegte Entscheidung. Benutzer können die Stile präzise über CSS-Selektoren anpassen, und die HTML-Struktur wird klarer.
• ESM-Reexport-Überschreibung: Wenn Änderungen an CSS nicht ausreichen, um Anpassungsbedürfnisse zu erfüllen, kann eine tiefere Anpassung über JS vorgenommen werden. Im theme/index.tsx kann durch ESM-Reexport jede eingebaute Komponente von Rspress überschrieben werden.
• Komponenten-Eject: Du kannst den brandneuen Befehl rspress eject [component] verwenden, der den Quellcode der angegebenen Komponente in das Verzeichnis theme/components/ kopiert. Du kannst diesen Code frei ändern oder sogar direkt von KI ändern lassen, um tiefere Anpassungen zu erreichen.

Navigationsleiste, Seitenleisten-Tag

Rspress 2.0 hat die Tag-Komponente implementiert, jetzt kannst du das tag-Attribut im Frontmatter verwenden, um UI-Markierungen in der Seitenleiste oder Navigationsleiste vorzunehmen.

Eingebaute Mehrsprachige Unterstützung

In der Version 1.x hatte Rspress nur englischen Text eingebaut. Wenn andere Sprachen wie zh verwendet wurden, musste der gesamte Text konfiguriert werden, was umständlich war. Jetzt hat das 2.0-Thema eingebaute Übersetzungstexte in mehreren Sprachen wie zh, en, ja, ko, ru usw. Das System führt basierend auf der Sprachkonfiguration automatisch "Tree Shaking" durch und packt nur die Texte und Sprachen, die du verwendest.

llms.txt Unterstützung

Rspress hat jetzt die Fähigkeit zur Generierung von llms.txt in den Kern integriert und eine brandneue SSG-MD (Static Site Generation to Markdown, statische Seiten Markdown-Generierung) Fähigkeit implementiert.

In front-end-Frameworks, die auf React basieren, gibt es oft das Problem, dass statische Informationen schwer zu extrahieren sind, und Rspress steht vor der gleichen Herausforderung. Rspress ermöglicht es Benutzern, die Ausdruckskraft von Dokumenten durch MDX-Snippets, React-Komponenten, Hooks und TSX-Routing zu verbessern. Aber diese dynamischen Inhalte stehen bei der Umwandlung in Markdown-Text vor folgenden Problemen:

• Direktes Eingeben von MDX in die KI enthält eine Menge Code-Syntaxrauschen und verliert den Inhalt von React-Komponenten.
• Das Umwandeln von HTML in Markdown hat oft schlechte Ergebnisse, die Informationsqualität ist schwer zu garantieren.

Um dieses Problem zu lösen, führt Rspress 2.0 die SSG-MD-Funktion ein. Dies ist eine brandneue Funktion, die ähnlich wie die statische Seitengenerierung (SSG) ist, sich jedoch darin unterscheidet, dass sie deine Seiten als Markdown-Dateien und nicht als HTML-Dateien rendert und die Dateien llms.txt und llms-full.txt generiert.

Shiki Kompilierungszeit Codeblock-HervorhebungRspress 2.0 verwendet standardmäßig Shiki für die Code-Hervorhebung. Im Vergleich zur Laufzeithervorhebungslösung von 1.x, die auf Prism basiert, führt Shiki die Hervorhebung zur Compile-Zeit durch.

• Unterstützt verschiedene Themenstile, zum Beispiel kann man auf der CSS-Variablen-Seite interaktiv zwischen verschiedenen Shiki-Themen wechseln und diese Vorschau anzeigen.
• Gleichzeitig erlaubt Shiki die Verwendung von benutzerdefinierten Transformatoren zur Erweiterung, um das Schreiben zu bereichern, wie zum Beispiel twoslash usw.
• Programmiersprachen werden bedarfsgerecht importiert, ohne Laufzeitausgaben und Paketgröße zu erhöhen.
• Basierend auf der TextMate-Syntax wird eine präzise Syntaxhervorhebung erreicht, die mit VS Code übereinstimmt.

Verbesserungen der Build-Leistung

Rspress 2.0 wird von Rsbuild und der Preview-Version von Rspack 2.0 unterstützt und hat standardmäßig die bedarfsgerechte Kompilierung und persistente Caching aktiviert.

Bedarfsorientierte Kompilierung

Standardmäßig ist dev.lazyCompilation aktiviert, wodurch eine Seite nur dann kompiliert wird, wenn du auf diese zugreifst. Dies verbessert die Entwicklungsstartgeschwindigkeit erheblich und ermöglicht sogar einen Kaltstart im Millisekundenbereich. Rspress implementiert auch eine Preload-Strategie für Routen, bei der die Zielrouten-Seite vorab geladen wird, wenn der Mauszeiger über den Link schwebt, was zusammen mit lazyCompilation ein verlustfreies Entwicklungserlebnis ermöglicht.

Persistentes Caching

2.0 aktiviert standardmäßig auch persistentes Caching, das die Ergebnisse der letzten Kompilierung im heißen Start wiederverwendet und die Build-Geschwindigkeit um 30%-60% erhöht. Das bedeutet, dass die Startgeschwindigkeit nach dem ersten Ausführen von rspress dev oder rspress build deutlich verbessert wird.

Dokumentationsentwicklungserlebnis

Standardmäßig aktivierte Überprüfung auf tote Links

Rspress 2.0 aktiviert standardmäßig die Überprüfung auf tote Links. Während des Build-Prozesses werden ungültige Links in der Dokumentation automatisch erkannt, um dir zu helfen, diese rechtzeitig zu finden und zu beheben.

Datei-Codeblöcke

Du kannst das Attribut file="./path/to/file" verwenden, um externe Dateien als Inhalt von Codeblöcken zu referenzieren und Beispielcode in separaten Dateien zu pflegen.

Flexiblere Verwendung von meta in preview

@rspress/plugin-preview verwendet jetzt das meta-Attribut, was flexibler ist und auch mit Datei-Codeblöcken kombiniert werden kann.

Rslib & Rspress

Wenn du ein Projekt mit create-rslib erstellst, kannst du jetzt das Rspress-Tool auswählen. Dies ermöglicht es dir, während der Entwicklung einer Komponentenbibliothek schnell eine passende Dokumentationsseite zu erstellen, um die Verwendung der Komponenten zu dokumentieren, API-Referenzen anzuzeigen oder die Komponenten in Echtzeit zu präsentieren.

Weitere offizielle Rspress-Plugins

Rspress 2.0 hat mehrere offizielle Plugins hinzugefügt:

• @rspress/plugin-algolia: Unterstützt den Austausch der integrierten Suche von Rspress durch Algolia DocSearch
• @rspress/plugin-twoslash: Fügt TypeScript-Codeblöcken Typ-Hinweise hinzu
• @rspress/plugin-llms: Bietet die Fähigkeit zur Generierung von llms.txt für Projekte, die SSG und SSG-MD nicht unterstützen
• @rspress/plugin-sitemap: Generiert automatisch Sitemap-Dateien zur Optimierung von SEO

Breaking Changes

Migration von Rspress 1.x

Wenn du ein Benutzer eines 1.x-Projekts bist, haben wir ein detailliertes Migrationsdokument vorbereitet, das dir hilft, von 1.x auf 2.0 zu aktualisieren. Du kannst die Funktion "Markdown kopieren" auf der Seite direkt verwenden und sie in deinen bevorzugten Codierungsagenten (wie Claude Code usw.) eingeben, um die Migration abzuschließen.Rspress 2.0 erfordert Node.js Version 20+ und React Version 18+.\n\n## Nächste Schritte\n\nDie Veröffentlichung von Rspress 2.0 ist nur ein neuer Anfang. Nach dieser Veröffentlichung wird Rspress kontinuierlich iterieren:\n\n- Förderung der ökologischen Integration: Eine tiefere Integration mit Rslib und Rstest, um eine integrierte Entwicklungserfahrung für Frontend-Projekte und Komponentenbibliotheksprojekte zu bieten.\n- Erforschung einer tieferen Integration von KI und Dokumentation: Wie intelligente Fragen und Antworten, automatische Zusammenfassungen usw.; Verbesserung von SSG-MD, um es stabiler und benutzerfreundlicher zu machen.\n\nNutzen Sie Rspress 2.0 sofort oder aktualisieren Sie auf die neueste Version, um eine brandneue Dokumentationsentwicklungserfahrung zu erleben!\n\nnpm create rspress@latest