30 января 2026

#Анонс Rspress 2.0

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

Rspress — это генератор статических сайтов, построенный на базе Rsbuild, предназначенный для создания сайтов документации для разработчиков. С момента первого релиза в 2023 году Rspress 1.x прошёл через 144 выпуска, в проекте приняли участие 125 контрибьюторов. Всё больше разработчиков выбирают Rspress благодаря высокой скорости компиляции, маршрутизации на основе соглашений и предпросмотру компонентов библиотеки для создания красивых и надёжных сайтов документации.

На основе отзывов сообщества Rspress 2.0 вносит значительные улучшения в эстетику темы, AI-нативные возможности, опыт разработки документации, интеграцию с Rslib и многое другое.

#Почему Rspress 2.0

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

• Стилизация темы: Более красивая тема по умолчанию, а также несколько подходов к кастомизации темы, решающие проблему отсутствия стабильных API для кастомизации темы в 1.x.

• AI-нативность: Документация предназначена не только для чтения людьми, но и должна лучше пониматься и использоваться Агентами. Теперь в Rspress встроена генерация llms.txt и возможность SSG-MD, основанная на SSG, которая генерирует качественный Markdown-контент для чтения Агентами.

• lazyCompilation, мгновенный запуск: lazyCompilation включён по умолчанию, в сочетании с предзагрузкой ресурсов при наведении на ссылку — компилируются только необходимые файлы при посещении конкретных маршрутов, обеспечивая мгновенный запуск независимо от размера проекта.

• Подсветка кода Shiki: Shiki интегрирован по умолчанию, обеспечивая подсветку синтаксиса во время сборки, с поддержкой переключения тем и расширений-трансформеров, таких как @rspress/plugin-twoslash, что даёт более богатые эффекты отображения блоков кода.

• Опыт разработки документации: Оптимизирован HMR для файлов _nav.json, _meta.json и других; добавлена json schema для подсказок кода в IDE; проверка битых ссылок включена по умолчанию; новая синтаксическая конструкция для блоков кода с поддержкой ссылок на внешние файлы; @rspress/plugin-preview и @rspress/plugin-playground теперь могут использоваться одновременно.

• Интеграция с Rslib: Теперь при создании проекта библиотеки компонентов с помощью create-rslib можно выбрать Rspress в качестве инструмента документации, быстро настраивая сайт документации компонентов.

Это всестороннее обновление существующей архитектуры. Ниже мы представляем Rspress 2.0 и его совершенно новую тему, высококачественную генерацию llms.txt, интеграцию Shiki, lazyCompilation и другие важные возможности.

#Новые возможности 2.0

#Совершенно новая тема

Тема по умолчанию в 2.0 прошла системное обновление, разработанное дизайнером @Zovn Wei, с значительными улучшениями в визуальных эффектах и опыте чтения. Каждый компонент может быть заменён индивидуально, обеспечивая высокую кастомизируемость.

#Кастомизация темы

От низкого к высокому уровню кастомизации существует четыре подхода к кастомизации темы: переменные CSS, имена классов BEM, повторный экспорт ESM с переопределением и извлечение компонентов.

• Переменные CSS: Новая тема предоставляет больше переменных CSS, охватывающих цвета темы, блоки кода, стили главной страницы и многое другое. Вы можете интерактивно просматривать и настраивать все переменные CSS на странице CSS-переменные, а затем скопировать конфигурацию напрямую в свой проект, как только найдёте подходящую настройку.

:root {
  /* Пользовательские цвета темы */
  --rp-c-brand: #3451b2;
  --rp-c-brand-dark: #2e4599;
  /* Пользовательские стили блоков кода */
  --rp-code-block-bg: #1e1e1e;
}

• Имена классов BEM: Все встроенные компоненты теперь используют соглашение об именовании BEM. Это старомодный выбор, но хорошо продуманный. Пользователи могут точно настраивать стили через CSS-селекторы, получая более понятную структуру HTML; при этом происходит полное отделение от любого CSS-фреймворка, который использует пользователь, что позволяет свободно выбирать CSS-фреймворки (Tailwind, Less, Sass и т. д.), например, использовать Tailwind V4 или V3 без опасений конфликтов версий со встроенным CSS Rspress.

/* Соглашение об именовании BEM */
.rp-[component-name]__[element-name]--[modifier-name] {
}

/* Легко переопределять стили компонентов с помощью имён классов BEM */
.rp-nav__title {
  height: 32px;
}
.rp-nav-menu__item--active {
  color: purple;
}

• Повторный экспорт ESM с переопределением: Если модификации через CSS не удовлетворяют ваши потребности в кастомизации, вы можете выполнить более глубокую настройку через JavaScript. Используя повторный экспорт ESM в файле theme/index.tsx, вы можете переопределить любой встроенный компонент Rspress.

import { Layout as BasicLayout } from '@rspress/core/theme-original';

const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;

export { Layout }; 
export * from '@rspress/core/theme-original'; 

• Извлечение компонента: Вы можете использовать новую команду rspress eject [component], которая копирует исходный код указанного компонента в директорию theme/components/. Вы можете свободно модифицировать этот код или даже передать его ИИ для изменений, чтобы добиться глубокой кастомизации.

# Экспорт компонента DocFooter в директорию темы
rspress eject DocFooter

#Теги в навигационной панели и боковой панели

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

---
tag: new, experimental # Отображаются в H1 и боковой панели
---

import { Tag } from '@rspress/core/theme';

# Тег

## Общие теги <Tag tag="new" /> {/* отображаются в правой боковой панели (оглавлении) */}

#Встроенная поддержка нескольких языков

В версии 1.x в Rspress была встроена только английская локализация. Использование других языков, таких как zh, требовало ручной настройки всех текстов, что было довольно хлопотно. Теперь тема 2.0 включает встроенные переводы для zh, en, ja, ko, ru и ряда других языков. Система автоматически выполняет «Tree Shaking» на основе конфигурации языка и фактического использования, подключая только те тексты и языки, которые вы реально используете. Для языков, не входящих в список встроенных, будет происходить откат к английскому тексту (en). Вы также можете расширять или переопределять переводы с помощью опции конфигурации i18nSource.

В будущем Rspress будет поддерживать ещё больше встроенных языков. Если вас это интересует, ознакомьтесь с этим пулреквестом от контрибьютора.

#llms.txt: SSG-MD для высококачественного Markdown-контента

Теперь Rspress интегрирует генерацию llms.txt непосредственно в ядро и реализует новую возможность SSG-MD (Static Site Generation to Markdown).

В фронтенд-фреймворках на основе React с динамическим рендерингом часто сложно извлекать статическую информацию, и Rspress сталкивался с той же проблемой. Rspress позволяет пользователям повышать выразительность документации с помощью MDX-фрагментов, React-компонентов, хуков и маршрутов на TSX. Однако при преобразовании такого динамического контента в обычный Markdown-текст возникают следующие проблемы:

• Прямая передача MDX в ИИ содержит большое количество синтаксического шума от кода и теряет содержимое React-компонентов
• Преобразование HTML в Markdown часто даёт низкое качество результата с ненадёжной информацией

Чтобы решить эту проблему, Rspress 2.0 вводит функцию SSG-MD. Это новая возможность, аналогичная Static Site Generation (SSG), но вместо рендеринга страниц в HTML-файлы она рендерит их в виде Markdown-файлов и генерирует файлы llms.txt и llms-full.txt.

По сравнению с традиционными подходами, такими как преобразование HTML в Markdown, SSG-MD имеет доступ к более богатым источникам информации во время рендеринга, таким как виртуальный DOM React, что приводит к более высокому качеству статической информации и большей гибкости.

Включить это очень просто:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
});

После сборки будет сгенерирована следующая структура:

doc_build
├── llms.txt
├── llms-full.txt
├── guide
│   └── start
│       └── introduction.md
└── ...

Если вы хотите настроить содержимое рендеринга в пользовательских компонентах, вы можете управлять этим через переменные окружения:

export function Tab({ label }: { label: string }) {
  if (import.meta.env.SSG_MD) {
    // В режиме SSG-MD выводим описание в виде простого текста
    return <>{`**Tab: ${label}**`}</>;
  }
  // В обычном режиме рендерим интерактивный компонент
  return <div className="tab">{label}</div>;
}

Это сохраняет интерактивный опыт работы с документацией, одновременно помогая ИИ лучше понимать семантическую информацию компонентов.

Подробности см. в Руководстве по использованию SSG-MD

#Подсветка блоков кода Shiki во время сборки

Rspress 2.0 по умолчанию использует Shiki для подсветки кода. По сравнению с подходом Prism в 1.x, где подсветка выполнялась во время выполнения, Shiki осуществляет подсветку на этапе компиляции.

1. Поддерживает множество стилей тем. Вы можете интерактивно переключать и просматривать разные темы Shiki на странице CSS-переменные.
2. Shiki также позволяет расширять функциональность через пользовательские трансформеры, чтобы обогатить написание, например, с помощью twoslash.
3. Языки программирования подключаются по требованию, не добавляя накладных расходов во время выполнения и не увеличивая размер бандла.
4. Обеспечивает точную подсветку синтаксиса, полностью соответствующую VS Code, на основе грамматики TextMate.

Вот несколько примеров трансформеров Shiki, чтобы вы почувствовали, какую творческую свободу в документации они открывают:

С использованием @rspress/plugin-twoslash

const hi = 'Привет';
const msg = `${hi}, мир`;
//    ^?

С использованием transformerNotationFocus

console.log('Не в фокусе');
console.log('В фокусе'); 
console.log('Не в фокусе');

Подробности см. в разделе Блоки кода

#Производительность сборки: lazyCompilation и постоянный кэш

Rspress 2.0 работает на Rsbuild и пре-релизе Rspack 2.0, с включёнными по умолчанию lazyCompilation и постоянным кэшем.

#lazyCompilation

dev.lazyCompilation включён по умолчанию — страницы компилируются только тогда, когда вы их посещаете, что значительно ускоряет запуск в режиме разработки и даже позволяет достичь холодного старта на уровне миллисекунд. Rspress также реализует стратегию предзагрузки маршрутов: при наведении курсора на ссылку происходит предзагрузка страницы целевого маршрута. Это работает в паре с lazyCompilation и обеспечивает разработку без потерь в скорости и удобстве.

#Постоянный кэш

2.0 также включает постоянный кэш по умолчанию, повторно используя результаты предыдущих компиляций при тёплых запусках, что ускоряет сборку на 30–60 %. Это означает, что после первого запуска rspress dev или rspress build в вашем проекте последующие запуски rspress будут заметно быстрее.

#Опыт разработки документации

#Проверка битых ссылок включена по умолчанию

Rspress 2.0 включает проверку битых ссылок по умолчанию. Во время процесса сборки автоматически обнаруживаются недействительные ссылки в документации, что помогает вам оперативно находить и исправлять проблемы.

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: true, // Включено по умолчанию, можно отключить значением false
    },
  },
});

Подробности см. в разделе Ссылки

#Блоки кода из файлов

Вы можете использовать атрибут file="./path/to/file", чтобы ссылаться на внешние файлы в качестве содержимого блока кода, храня примеры кода в отдельных файлах.

```ts file="./_demo.ts"

```

```tsx file="<root>/src/components/Button.tsx"

```

Подробности см. в разделе Блоки кода из файлов

#Более гибкое использование meta для предпросмотра

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

Вот пример использования предпросмотра через iframe для блока кода:

```tsx preview="iframe-follow" file="./_demo.ts"

```

Отобразится как:

import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

Кроме того, @rspress/plugin-playground теперь поддерживает совместное использование с plugin-preview, переключение осуществляется через мета-атрибуты, например: ```tsx playground

#Поддержка HMR для конфигурационных файлов

На основе переработанного плагина виртуальных модулей для Rsbuild теперь поддерживается HMR для файлов i18n.json, _nav.json, _meta.json, блоков кода из файлов, а также конфигураций, связанных с iframe в @rspress/plugin-preview. После изменения этих конфигурационных файлов страница будет автоматически обновляться в горячем режиме без необходимости ручного перезагрузки.

#Rslib & Rspress

При создании проекта с помощью create-rslib теперь можно выбрать инструмент Rspress. Это позволяет быстро настроить сайт документации параллельно с вашей библиотекой компонентов — для написания руководств по использованию, отображения справочника API или живого предпросмотра компонентов.

Выполните npm create rslib@latest и выберите Rspress, чтобы сгенерировать следующую структуру файлов:

├── docs
│   └── index.mdx
├── src
│   └── Button.tsx
├── package.json
├── tsconfig.json
├── rslib.config.ts
└── rspress.config.ts

Шаблон включает плагин rsbuild-plugin-workspace-dev, который автоматически запускает команду watch из Rslib параллельно с сервером разработки Rspress.

Просто выполните npm run doc, чтобы запустить сервер разработки Rspress и просмотреть вашу библиотеку компонентов Rslib:

{
  "scripts": {
    "dev": "rslib build --watch",
    "doc": "rspress dev" // Запустите эту команду
  }
}

#Новые официальные плагины Rspress

Rspress 2.0 добавил несколько официальных плагинов:

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

#Другие критические изменения

#Миграция с Rspress 1.x

Если вы пользователь версии 1.x, мы подготовили подробное руководство по миграции, которое поможет вам обновиться до версии 2.0.

Вы можете воспользоваться функцией «Copy Markdown» на странице и передать скопированный текст вашему любимому агенту для кодирования (например, Claude Code), чтобы завершить миграцию.

Пожалуйста, ознакомьтесь с Руководством по миграции.

#Удаление конфигурации mdxRs

Мы заметили, что значительная часть пользователей 1.x активно отключала mdxRs, чтобы использовать Shiki, функции предпросмотра библиотек компонентов и собственные плагины remark/rehype. С включёнными lazyCompilation и постоянным кэшем оптимизация производительности уже достаточно значительна даже при использовании JS-версии парсера MDX.

В обмен на лучшую расширяемость и поддерживаемость мы приняли решение отказаться от использования парсера MDX на Rust (@rspress/mdx-rs) в конвейере компиляции Markdown/MDX. Это позволяет Rspress лучше интегрировать инструменты из JavaScript-экосистемы, такие как Shiki.

#Требования к версиям Node.js и upstream-зависимостей

Rspress 2.0 требует Node.js версии 20+ и React версии 18+.

#Изменения в именах пакетов и путях импорта

Rspress объединил пакеты rspress, @rspress/runtime, @rspress/shared и @rspress/theme-default в единый пакет @rspress/core. Теперь проекты и плагины должны устанавливать только один пакет — @rspress/core.

{
  "dependencies": {
-   "rspress": "1.x"
-   "@rspress/shared": "1.x"
+   "@rspress/core": "^2.0.0"
  }
}

- import { defineConfig } from 'rspress/config';
+ import { defineConfig } from '@rspress/core';

- import { useDark } from 'rspress/runtime'
- import { PackageManagerTabs } from 'rspress/theme';
+ import { useDark } from '@rspress/core/runtime'
+ import { PackageManagerTabs } from '@rspress/core/theme';

Если вы разработали плагин для Rspress, пожалуйста, измените в вашем плагине peerDependencies с rspress на @rspress/core:

{
  "peerDependencies": {
    "@rspress/core": "^2.0.0"
  }
}

#Следующие шаги

Выпуск Rspress 2.0 — это лишь новое начало. После этого релиза Rspress продолжит развиваться:

• Углубление интеграции с экосистемой: Более тесная интеграция с Rslib и Rstest, чтобы обеспечить единый опыт разработки для фронтенд-проектов и проектов библиотек компонентов.

• Более глубокая интеграция ИИ и документации: Например, интеллектуальные вопросы-ответы, автоматическая суммаризация и многое другое; доработка SSG-MD для большей стабильности и удобства использования.

Спасибо всем разработчикам и пользователям, которые внесли свой вклад в Rspress! Если во время использования вы столкнётесь с проблемами или у вас появятся предложения, пожалуйста, оставляйте обратную связь в GitHub Issues.

Обновляйтесь до Rspress 2.0 прямо сейчас и откройте для себя совершенно новый опыт разработки документации!

npm create rspress@latest

yarn create rspress

pnpm create rspress@latest

bun create rspress@latest

deno init --npm rspress@latest