Rspress 2.0 выпущен: новое обновление, ориентированное на опыт и ИИ
Rspress 2.0 выпущен: новое обновление, ориентированное на опыт и ИИ
Мы рады объявить о официальном выпуске 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, в сочетании с функцией предварительной загрузки ресурсов при наведении на ссылки, файлы создаются только при доступе к определенному маршруту, что позволяет мгновенно запускать dev, независимо от размера проекта.
- Подсветка кода Shiki: по умолчанию интегрирован Shiki, который завершает подсветку синтаксиса во время сборки, поддерживает переключение тем, расширения transformer, такие как @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 номенклатуру. Это довольно старомодный выбор, но это также наше тщательно продуманное решение. Пользователи могут точно настраивать стили с помощью CSS селекторов, структура HTML становится более ясной.
- ESM повторный экспорт перекрытия: если изменения в CSS не удовлетворяют потребностям кастомизации, можно провести более глубокую настройку с помощью JS. Используя ESM повторный экспорт в theme/index.tsx, можно перекрыть любой встроенный компонент Rspress.
- Извлечение компонента: вы можете использовать новую команду rspress eject [component], которая скопирует исходный код указанного компонента в каталог theme/components/, вы можете свободно изменять этот код, даже передать его AI для изменения, чтобы достичь глубокой кастомизации.
Навигационная панель, боковая панель тегов
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 в core и реализовал новую способность SSG-MD (Static Site Generation to Markdown, генерация статического сайта в Markdown).
В рамках фронтенд-фреймов, основанных на динамическом рендеринге React, часто возникает проблема с трудностью извлечения статической информации, и Rspress сталкивается с той же проблемой. Rspress позволяет пользователям улучшать выразительность документа с помощью динамических функций, таких как фрагменты MDX, компоненты React, хуки и маршруты TSX. Однако эти динамические содержимое сталкиваются со следующими проблемами при преобразовании в текст Markdown:
- Прямое предоставление MDX AI будет содержать много синтаксического шума кода и потеряет содержимое компонентов React.
- Преобразование HTML в Markdown часто дает плохие результаты, качество информации трудно гарантировать.
Чтобы решить эту проблему, Rspress 2.0 вводит функцию SSG-MD. Это совершенно новая функция, которая похожа на статическую генерацию сайта (SSG), но отличается тем, что она рендерит ваши страницы в файлы Markdown, а не в HTML файлы, и генерирует файлы llms.txt и llms-full.txt.
Подсветка синтаксиса кодовых блоков ShikiRspress 2.0 по умолчанию использует Shiki для подсветки кода. В отличие от решения по подсветке времени выполнения prism 1.x, 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" для ссылки на внешние файлы в качестве содержимого кодового блока, поддерживая пример кода в отдельном файле.
Более гибкое использование meta в preview
@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 для повышения стабильности и удобства использования.
npm create rspress@latest
