Rspress 2.0 Публикация: Ново обновление, насочено към опит и AI

С радост обявяваме официалната публикация на Rspress 2.0!

Rspress е статичен генератор на сайтове, базиран на Rsbuild, създаден специално за разработчици и документи. От официалната си публикация през 2023 г., Rspress 1.x е преминал през 144 версии, с участието на 125 сътрудници в разработката на проекта. Все повече разработчици избират Rspress, благодарение на високата производителност на компилация, конвенционалната маршрутизация и предварителния преглед на библиотеката от компоненти, за да изградят красиви и надеждни документални сайтове.

На базата на обратната връзка и предложения от общността, Rspress 2.0 напредва в естетиката на темите, AI-native, опита при разработка на документи, използване с Rslib и други области.

Защо Rspress 2.0

Rspress 1.x вече реши проблема с производителността на компилацията на рамката за документални сайтове, но все още съществуват някои проблеми, които влияят на основния опит като инструмент за разработка на документи. Версия 2.0 не само ще се стреми към производителността на компилация, но също така ще се фокусира и върху други аспекти на опита на документалния сайт:

• Стил на темата: Комплект от по-красиви по подразбиране теми, с множество опции за персонализиране, решаващи проблема с нестабилния API за персонализиране на теми в 1.x.
• AI-native: Документите не само служат на човешките читатели, но също така трябва да бъдат по-добре разбрани и използвани от агенти. Rspress сега вгражда функции за генериране на llms.txt и SSG-MD, произтичащи от SSG, за генериране на висококачествено съдържание в Markdown формат за четене от агенти.
• Компилация при поискване, мигновен старт: По подразбиране е активирана lazyCompilation, в комбинация с функцията за предварително зареждане на ресурси при задържане на курсора върху линкове, изгражда необходимите файлове само при достъп до определен маршрут, осигурявайки мигновен старт независимо от размера на проекта.
• Shiki синтаксисно оцветяване: По подразбиране интегрира Shiki, завършвайки синтаксичното оцветяване по време на изграждане, поддържа смяна на теми и разширения на трансформатори, като @rspress/plugin-twoslash, предоставяйки по-богати визуализации на блоковете с код.
• Опит при разработка на документи: Оптимизиране на HMR за файлове като nav.json, meta.json и добавяне на json схема за кодови подсказки в IDE; по подразбиране е активирана функцията за проверка на мъртви линкове; добавена е синтаксис за файлови блокове, поддържаща референции към външни файлове; @rspress/plugin-preview и @rspress/plugin-playground поддържат едновременно използване и др.
• Интеграция с Rslib: Сега можете да изберете Rspress като инструмент за документи, когато създавате проект за библиотека от компоненти с create-rslib, за бързо изграждане на документален сайт за компоненти.

2.0 Нови функции

Напълно нова тема

По подразбиране темата 2.0 получава системно обновление, проектирано от дизайнерския екип @Zovn Wei, с голямо подобрение в визуалния ефект и опита на четене, като всеки компонент може да бъде заменен независимо, осигурявайки висока степен на персонализиране.

Персонализиране на темата

Според степента на персонализиране от ниска до висока, има четири начина за персонализиране на темата: CSS променливи, BEM класове, ESM повторно изнасяне и извеждане на компоненти.- CSS променливи: Новата тема разкрива повече CSS променливи, които покриват стиловете на темата, кодовите блокове, началната страница и др. Можете интерактивно да прегледате и коригирате всички CSS променливи на страницата с CSS променливи и след като намерите удовлетворителна конфигурация, просто я копирайте за използване в проекта.

• BEM имена на класове: Вградените компоненти сега използват BEM именувателна конвенция. Това е много Old School избор, но също така е добре обмислено решение. Потребителите могат прецизно да коригират стиловете чрез CSS селектори, а HTML структурата е по-ясна.
• ESM повторно експортиране: Ако промените в CSS не отговарят на нуждите за персонализиране, можете да направите по-дълбоко персонализиране чрез JS. В theme/index.tsx, използвайки ESM повторно експортиране, можете да замените всеки вграден компонент на Rspress.
• Изваждане на компоненти: Можете да използвате новата команда rspress eject [component], която ще копира изходния код на посочения компонент в директорията theme/components/, където можете свободно да модифицирате този код, дори да го предадете на AI за модификация, за да постигнете дълбоко персонализиране.

Навигационен бар, страничен бар tag

Rspress 2.0 реализира компонента Tag, сега можете да използвате атрибута tag в frontmatter, за да направите UI маркировка в страничния бар или навигационния бар.

Вградена поддръжка на много езици

В версия 1.x, Rspress имаше вградени само английски текстове, ако използвате друг език, например zh, трябваше да конфигурирате всички текстове, което беше доста сложно. Сега темата 2.0 вгражда преводни текстове на множество езици, включително zh, en, ja, ko, ru и др., а системата автоматично извършва "Tree Shaking" в зависимост от конфигурацията на езика, опаковайки само текстовете и езиците, които използвате.

Поддръжка на llms.txt

Rspress сега интегрира способността за генериране на llms.txt в основния код и реализира нова способност SSG-MD (Static Site Generation to Markdown, генериране на статичен сайт в Markdown).

В базираните на React динамично рендерирани фронтенд рамки често съществува проблем с извличането на статична информация, Rspress също се сблъсква с подобно предизвикателство. Rspress позволява на потребителите да подобрят изразителността на документацията чрез MDX фрагменти, React компоненти, Hooks и TSX маршрути и други динамични характеристики. Но тези динамични съдържания срещат следните проблеми при преобразуването в Markdown текст:

• Прякото подаване на MDX на AI ще съдържа много синтактични шумове и ще загуби съдържанието на React компонентите.
• Преобразуването на HTML в Markdown често не дава добри резултати, качеството на информацията е трудно да се гарантира.

За да реши този проблем, Rspress 2.0 въвежда функцията SSG-MD. Това е нова функция, която е подобна на статичното генериране на сайтове (SSG), но разликата е, че тя рендерира вашите страници като Markdown файлове, а не HTML файлове, и генерира свързани файлове llms.txt и llms-full.txt.

Shiki компилиране на кодови блокове с подсветкаRspress 2.0 по подразбиране използва Shiki за синтактично оцветяване на кода. В сравнение с 1.x решение за синтактично оцветяване на prism, Shiki завършва обработката на оцветяването по време на компилация.

• Поддържа множество стилове на теми, например на страницата с CSS променливи можете интерактивно да превключвате и преглеждате различни теми на Shiki.
• Също така Shiki позволява използването на персонализирани трансформатори за разширяване на писането, например twoslash и др.
• Включва програмни езици по необходимост, без да увеличава разходите за време на изпълнение и размера на пакета.
• Основано на синтаксиса на TextMate, предоставя точно синтактично оцветяване, съвместимо с VS Code.

Подобрение на производителността на изграждане

Rspress 2.0 е базиран на Rsbuild и Rspack 2.0 предварителна версия, като по подразбиране е активирано компилиране по необходимост и персистентно кеширане.

Компилиране по необходимост

По подразбиране е активирано dev.lazyCompilation, само когато посетите определена страница, тя ще бъде компилирана, което значително увеличава скоростта на стартиране на разработката, дори постига милисекундно студено стартиране. Rspress също така реализира стратегия за предварително зареждане на маршрути, когато курсорът е над линка, целевата страница на маршрута ще бъде предварително заредена, в комбинация с lazyCompilation за постигане на беззагубно изживяване при разработка.

Персистентно кеширане

2.0 също така по подразбиране активира персистентно кеширане, което позволява повторно използване на резултатите от предишната компилация при горещо стартиране, увеличавайки скоростта на изграждане с 30%-60%. Това означава, че след първоначалното стартиране на rspress dev или rspress build, последващата скорост на стартиране ще бъде значително увеличена.

Изживяване при разработка на документация

По подразбиране активирано проверка на мъртви линкове

Rspress 2.0 по подразбиране активира функцията за проверка на мъртви линкове. По време на изграждането автоматично ще се проверяват невалидни линкове в документацията, за да ви помогне да ги откриете и поправите навреме.

Кодови блокове на файлове

Можете да използвате атрибута file="./path/to/file" за да се позовете на външни файлове като съдържание на кодов блок, като поддържате примерния код в отделен файл.

preview по-гъвкаво използване на meta

@rspress/plugin-preview сега използва атрибута meta, което е по-гъвкаво и може да се комбинира с кодови блокове на файлове.

Rslib & Rspress

Когато използвате create-rslib за създаване на проект, сега можете да изберете инструмента Rspress. Това ви позволява бързо да изградите свързания сайт за документация, докато разработвате библиотека от компоненти, за написване на инструкции за използване на компонентите, показване на API референции или в реално време преглед на ефектите на компонентите.

Още официални плъгини на Rspress

Rspress 2.0 добави няколко нови официални плъгини:

• @rspress/plugin-algolia: Поддържа замяна на вграденото търсене на Rspress с Algolia DocSearch
• @rspress/plugin-twoslash: Добавя типови подсказки за блокове с TypeScript код
• @rspress/plugin-llms: Предоставя способност за генериране на llms.txt за проекти, които не поддържат SSG и SSG-MD
• @rspress/plugin-sitemap: Автоматично генерира Sitemap файл за оптимизиране на SEO

Промени, които нарушават съвместимостта

Миграция от Rspress 1.x

Ако сте потребител на проект 1.x, подготвили сме подробна документация за миграция, за да ви помогнем да надстроите от 1.x до 2.0. Можете директно да използвате функцията "Копиране на Markdown" на страницата, за да я въведете на вашия обичаен кодов агент (като Claude Code и др.) за завършване на миграцията.### Node.js и изисквания за версии на зависимостите

Rspress 2.0 изисква версия на Node.js 20+, версия на React 18+.

Следващи стъпки

Пускането на Rspress 2.0 е само ново начало. След това издание, Rspress ще продължи да се итеративно развива:

• Напредък в интеграцията на екосистемата: По-дълбока интеграция с Rslib, Rstest, предоставяйки интегрирано разработващо изживяване за фронтенд проекти и проекти на компоненти.
• Изследване на по-дълбока интеграция на AI и документация: Например, интелигентни въпроси и отговори, автоматични резюмета и др.; усъвършенстване на SSG-MD, за да бъде стабилен и по-лесен за използване.

Използвайте или обновете до Rspress 2.0 сега, за да изживеете новото пътешествие в разработката на документация!

npm create rspress@latest