Rspress 2.0 випущено: нове оновлення, орієнтоване на досвід та AI
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 schema для підказок коду в 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. У theme/index.tsx за допомогою ESM повторного експорту можна перекрити будь-який з вбудованих компонентів Rspress.
- Виведення компонентів: ви можете використовувати нову команду rspress eject [component], яка скопіює вихідний код вказаного компонента до каталогу theme/components/, ви можете вільно змінювати цей код, навіть передати його AI для зміни, щоб досягти глибокої кастомізації.
Навігаційна панель, бічна панель тегів
Rspress 2.0 реалізував компонент тегів, тепер ви можете використовувати атрибут тегу в 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 компонентів, Hooks та 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
