Publication de Rspress 2.0 : une mise à niveau entièrement axée sur l'expérience et l'IA

Nous sommes ravis d'annoncer la publication officielle de Rspress 2.0 !

Rspress est un générateur de sites statiques basé sur Rsbuild, conçu comme un outil de documentation pour les développeurs. Depuis sa publication officielle en 2023, Rspress 1.x a connu 144 versions itérées, avec 125 contributeurs participant au développement du projet. De plus en plus de développeurs choisissent Rspress, profitant de ses fonctionnalités telles que des performances de compilation efficaces, un routage basé sur des conventions et un aperçu de la bibliothèque de composants pour créer des sites de documentation à la fois esthétiques et fiables.

Sur la base des retours et suggestions de la communauté, Rspress 2.0 fait un pas en avant dans des domaines tels que l'esthétique des thèmes, l'IA native, l'expérience de développement de documentation, et l'utilisation conjointe avec Rslib.

Pourquoi Rspress 2.0

Rspress 1.x a déjà résolu les problèmes de performance de compilation du cadre de documentation, mais il reste encore des problèmes qui affectent l'expérience centrale en tant qu'outil de développement de documentation. La version 2.0 ne se limite pas à la recherche de performances de compilation, mais se concentre également sur d'autres aspects de l'expérience de site de documentation :

• Styles de thème : un nouveau thème par défaut plus esthétique, avec plusieurs façons de personnaliser le thème, résolvant le problème de manque d'API stable pour la personnalisation des thèmes dans 1.x.
• IA native : la documentation ne sert pas seulement les lecteurs humains, elle doit également être mieux comprise et utilisée par les Agents. Rspress intègre désormais la génération de llms.txt et la fonctionnalité SSG-MD dérivée de SSG, produisant un contenu Markdown de haute qualité pour la lecture par les Agents.
• Compilation à la demande, démarrage instantané : activation par défaut de lazyCompilation, associée à la fonction de préchargement des ressources lors du survol des liens, construisant uniquement les fichiers nécessaires lors de l'accès à des routes spécifiques, permettant un démarrage instantané quel que soit l'ampleur du projet.
• Mise en surbrillance du code Shiki : intégration par défaut de Shiki, réalisant la mise en surbrillance de la syntaxe lors de la construction, prenant en charge le changement de thème, les extensions de transformateur, telles que @rspress/plugin-twoslash, offrant des effets d'affichage de blocs de code plus riches.
• Expérience de développement de documentation : optimisation de HMR pour des fichiers comme nav.json, meta.json, et ajout d'un schéma json pour les suggestions de code dans l'IDE ; vérification des liens morts activée par défaut ; ajout d'une syntaxe de bloc de code pour les fichiers, prenant en charge la référence à des fichiers externes ; @rspress/plugin-preview et @rspress/plugin-playground prenant en charge une utilisation simultanée, etc.
• Intégration de Rslib : il est désormais possible de choisir Rspress comme outil de documentation lors de la création d'un projet de bibliothèque de composants avec create-rslib, permettant de créer rapidement un site de documentation pour les composants.

Nouvelles fonctionnalités 2.0

Nouveau thème

Le thème par défaut de 2.0 a bénéficié d'une mise à niveau systématique, conçu par le designer de l'équipe @Zovn Wei, avec des améliorations significatives en termes d'effets visuels et d'expérience de lecture, et chaque composant peut être remplacé indépendamment, offrant une grande personnalisation.

Personnalisation du thème

Selon le degré de personnalisation, il existe quatre façons de personnaliser le thème : variables CSS, noms de classes BEM, réexportation ESM, et éjection de composants.- Variables CSS : Le nouveau thème expose plus de variables CSS, couvrant les styles de couleur de thème, de blocs de code, de page d'accueil, etc. Vous pouvez prévisualiser et ajuster toutes les variables CSS de manière interactive sur la page des variables CSS, et une fois que vous avez trouvé la configuration qui vous satisfait, vous pouvez la copier directement dans votre projet.

• Noms de classe BEM : Les composants intégrés utilisent désormais la norme de nommage BEM. C'est un choix très Old School, mais c'est aussi une décision mûrement réfléchie. Les utilisateurs peuvent ajuster les styles avec précision grâce aux sélecteurs CSS, rendant la structure HTML plus claire.
• Réexportation ESM : Si les modifications CSS ne répondent pas aux besoins de personnalisation, vous pouvez effectuer une personnalisation plus approfondie via JS. Dans theme/index.tsx, en utilisant la réexportation ESM, vous pouvez écraser n'importe quel composant intégré de Rspress.
• Éjection de composant : Vous pouvez utiliser la nouvelle commande rspress eject [component], qui copiera le code source du composant spécifié dans le répertoire theme/components/. Vous pouvez modifier ce code librement, voire le confier directement à l'IA pour une personnalisation approfondie.

Tag de barre de navigation et de barre latérale

Rspress 2.0 a implémenté le composant Tag, vous pouvez maintenant utiliser la propriété tag dans le frontmatter pour annoter l'UI dans la barre latérale ou la barre de navigation.

Support multilingue intégré

Dans la version 1.x, Rspress n'avait intégré que du texte en anglais. Si vous utilisez d'autres langues comme le zh, vous devez configurer tous les textes, ce qui est assez fastidieux. Maintenant, le thème 2.0 intègre des textes traduits en plusieurs langues comme le zh, en, ja, ko, ru, etc. Le système effectuera automatiquement un "Tree Shaking" en fonction de la configuration linguistique, ne packant que les textes et langues que vous utilisez.

Support llms.txt

Rspress intègre maintenant la capacité de génération llms.txt dans le core et a réalisé une toute nouvelle capacité SSG-MD (Static Site Generation to Markdown, génération de site statique en Markdown).

Dans les frameworks frontaux basés sur React, il existe souvent des problèmes d'extraction d'informations statiques, et Rspress fait face au même défi. Rspress permet aux utilisateurs d'améliorer l'expressivité des documents via des fragments MDX, des composants React, des Hooks et des routes TSX, ainsi que d'autres caractéristiques dynamiques. Cependant, ces contenus dynamiques rencontrent les problèmes suivants lors de leur conversion en texte Markdown :

• Donner directement l'entrée MDX à l'IA contiendra beaucoup de bruit syntaxique de code et perdra le contenu des composants React.
• Convertir HTML en Markdown donne souvent des résultats médiocres, et la qualité de l'information est difficile à garantir.

Pour résoudre ce problème, Rspress 2.0 introduit la fonctionnalité SSG-MD. C'est une toute nouvelle fonctionnalité, similaire à la génération de site statique (SSG), mais la différence est qu'elle rend vos pages en fichiers Markdown, plutôt qu'en fichiers HTML, et génère des fichiers llms.txt et llms-full.txt associés.

Mise en surbrillance des blocs de code à l'époque de ShikiRspress 2.0 utilise par défaut Shiki pour la mise en surbrillance du code. Comparé à la solution de mise en surbrillance à l'exécution de prism dans 1.x, Shiki effectue le traitement de mise en surbrillance à la compilation.

• Supporte plusieurs styles de thèmes, par exemple, sur la page des variables CSS, vous pouvez interagir et prévisualiser différents thèmes Shiki.
• En même temps, Shiki permet également d'utiliser des transformateurs personnalisés pour enrichir l'écriture, comme twoslash, etc.
• Importation à la demande des langages de programmation, sans augmenter le coût d'exécution et la taille du paquet.
• Basé sur la syntaxe TextMate, il réalise une mise en surbrillance syntaxique précise, identique à celle de VS Code.

Amélioration des performances de construction

Rspress 2.0 est alimenté par Rsbuild et la version préliminaire de Rspack 2.0, tout en activant par défaut la compilation à la demande et le cache persistant.

Compilation à la demande

La compilation à la demande est activée par défaut avec dev.lazyCompilation, ce qui signifie que seules les pages que vous visitez seront compilées, ce qui améliore considérablement la vitesse de démarrage du développement, atteignant même un démarrage à froid en millisecondes. Rspress a également mis en œuvre une stratégie de préchargement des routes, lorsque vous survolez un lien, la page de la route cible sera préchargée, offrant une expérience de développement sans perte avec lazyCompilation.

Cache persistant

La version 2.0 active également par défaut le cache persistant, réutilisant les résultats de compilation précédents lors des démarrages à chaud, ce qui améliore la vitesse de construction de 30 % à 60 %. Cela signifie qu'après le premier lancement de rspress dev ou rspress build, la vitesse de démarrage ultérieure sera nettement améliorée.

Expérience de développement de documentation

Vérification des liens morts activée par défaut

Rspress 2.0 active par défaut la fonction de vérification des liens morts. Pendant le processus de construction, il détectera automatiquement les liens invalides dans la documentation, vous aidant à les découvrir et à les corriger à temps.

Blocs de code de fichiers

Vous pouvez utiliser l'attribut file="./path/to/file" pour référencer des fichiers externes comme contenu de blocs de code, en maintenant le code d'exemple dans des fichiers séparés.

Utilisation de meta plus flexible pour preview

@rspress/plugin-preview utilise maintenant l'attribut meta, ce qui le rend plus flexible et peut également être associé à des blocs de code de fichiers.

Rslib & Rspress

Lors de l'utilisation de create-rslib pour créer un projet, vous pouvez maintenant choisir l'outil Rspress. Cela vous permet de construire rapidement un site de documentation associé tout en développant une bibliothèque de composants, pour rédiger des instructions d'utilisation des composants, afficher des références API, ou prévisualiser en temps réel l'effet des composants.

Plus de plugins officiels Rspress

Rspress 2.0 a ajouté plusieurs plugins officiels :

• @rspress/plugin-algolia : remplace la recherche intégrée de Rspress par Algolia DocSearch
• @rspress/plugin-twoslash : ajoute des suggestions de type pour les blocs de code TypeScript
• @rspress/plugin-llms : fournit la capacité de génération de llms.txt pour les projets ne supportant pas SSG et SSG-MD
• @rspress/plugin-sitemap : génère automatiquement des fichiers Sitemap pour optimiser le SEO

Changements majeurs

Migration depuis Rspress 1.x

Si vous êtes utilisateur d'un projet 1.x, nous avons préparé un document de migration détaillé pour vous aider à passer de 1.x à 2.0. Vous pouvez directement utiliser la fonction "Copier Markdown" sur la page, et l'entrer dans votre agent de codage habituel (comme Claude Code, etc.) pour effectuer la migration.### Node.js et exigences de version des dépendances en amont

Rspress 2.0 nécessite Node.js version 20+, React version 18+.

Prochaines étapes

La publication de Rspress 2.0 n'est qu'un nouveau point de départ. Après cette publication, Rspress continuera à itérer :

• Avancer l'intégration de l'écosystème : s'intégrer plus profondément avec Rslib, Rstest pour offrir une expérience de développement intégrée pour les projets front-end et les bibliothèques de composants.
• Explorer une intégration plus profonde de l'IA avec la documentation : comme les questions-réponses intelligentes, les résumés automatiques, etc. ; améliorer SSG-MD pour le rendre stable et plus facile à utiliser.

Utilisez ou mettez à niveau vers Rspress 2.0 maintenant pour vivre une toute nouvelle aventure de développement de documentation !

npm create rspress@latest