#Введение

Rspress — это генератор статических сайтов на базе Rsbuild, использующий для рендеринга фреймворк React. Он поставляется с готовой темой для документации, благодаря чему вы можете буквально за несколько минут создать полноценный сайт документации. При этом вы можете кастомизировать тему под свои нужды — например, сделать блог, лендинг продукта и т. д. Конечно, подключив официальные плагины, вы также легко сможете собрать документацию для библиотеки компонентов.

#Почему Rspress

Rspress создавался с акцентом на следующие ключевые возможности:

• Производительность сборки. Быстрый запуск разработки — залог приятного опыта.
• Нативно для ИИ. Техническая документация предназначена не только для чтения людьми, но и может быть лучше понята и использована искусственным интеллектом благодаря SSG-MD.
• Поддержка MDX. Благодаря MDX можно удобно переиспользовать фрагменты документов и встраивать в них любые React-компоненты.
• Базовый функционал сайта документации. Встроенная интернационализация, поддержка нескольких версий, полнотекстовый поиск, документация компонентных библиотек и многое другое.
• Расширяемость. Встроенная система плагинов и API для расширения возможностей Rspress.

Именно эти аспекты являются основными требованиями к современным статическим сайтам. Далее мы рассмотрим их подробнее.

#Производительность сборки

По мере роста проекта всё чаще возникает проблема долгого запуска dev-сервера, что заметно ухудшает процесс разработки. Чем дольше длится разработка проекта, тем сильнее это ощущается.

Мы задались вопросом: можно ли выйти за рамки существующих инструментов сообщества, пробить бутылочное горлышко текущих SSG-фреймворков и добиться практически мгновенного старта в большинстве сценариев?

Мы продолжили исследования в этом направлении и в итоге добились такого результата в Rspress.

В Rspress V2 мы значительно улучшили производительность благодаря нескольким методам оптимизации:

• Ленивая компиляция. В режиме разработки LazyCompilation выполняет компиляцию по требованию. Страницы компилируются только тогда, когда вы их посещаете, что существенно ускоряет запуск в процессе разработки и позволяет достичь холодного старта на уровне миллисекунд.
• Постоянный кэш. При сборке в продакшен-режиме постоянный кэш включён по умолчанию. Он позволяет повторно использовать результаты предыдущих компиляций при «тёплых» запусках, ускоряя процесс сборки на 30–60%.
• Бандлер Rspack. Rspress использует разработанный нашей командой бандлер Rspack. Rspack — это бандлер, написанный на Rust, со встроенными множественными методами оптимизации производительности, такими как многопоточная параллельная компиляция, инкрементальная компиляция и др. Он в 5–10 раз эффективнее традиционных инструментов сборки, существующих в сообществе.

При этом внутри Rspress также применяется множество других методов оптимизации сборки. Все эти оптимизации в сочетании с мощным фронтенд-инструментарием на Rust выводят производительность компиляции SSG-фреймворка на совершенно новый уровень.

#Нативно для ИИ

С развитием больших языковых моделей техническая документация должна служить не только людям, но и быть лучше понятой и использованной искусственным интеллектом.

Rspress V2 представляет возможность SSG-MD, которая рендерит страницы в виде Markdown-файлов вместо HTML и генерирует индексные файлы, соответствующие спецификации llms.txt.

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

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

После включения в выходных данных сборки будут созданы:

• llms.txt (индексный файл, содержащий заголовки страниц и описания в порядке навигации и боковой панели),
• llms-full.txt (полный файл, содержащий Markdown-контент всех страниц),
• а также файлы .md, соответствующие каждому маршруту.

Подобно тому, как SSG генерирует статические HTML-файлы для улучшения SEO, SSG-MD позволяет относительно улучшить GEO (Generative Engine Optimization) и качество статической информации для больших языковых моделей.

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

#Поддержка MDX

Чтобы обеспечить максимальную гибкость при написании контента, Rspress изначально поддерживает формат MDX.

MDX — это подход к компонентизации контента. Документы становятся компонентами: их фрагменты можно переиспользовать в разных местах, а внутри Markdown легко встраивать любые кастомные React-компоненты. Это кардинально повышает свободу и удобство работы с документацией.

#Базовые возможности сайта документации

Конечно, мы уделили большое внимание проработке стандартного функционала сайта документации. Rspress «из коробки» поддерживает:

• Автоматическую генерацию структуры сайта: навигационная панель, боковое меню и т. д.
• Генерацию полностью статического сайта — после продакшен-сборки получаем чистый HTML.
• Интернационализацию (i18n) и мультиязычные документы.
• Полнотекстовый поиск без дополнительной настройки.
• Управление несколькими версиями документации.
• Полную кастомизацию темы.
• Автоматическую генерацию демо-превью и интерактивной песочницы для компонентов.

Все эти возможности мы подробно разберём далее.

#Механизм расширений

Для максимальной гибкости в Rspress реализован целый набор механизмов расширения:

• Глобальные компоненты, стили и структура страниц → см. Кастомизация страниц.
• Расширение процесса сборки: собственная конфигурация Rspack, добавление плагинов MDX и др. → см. Расширение сборки.
• Полная кастомизация темы → см. Кастомная тема.
• Встроенная система плагинов с возможностью писать свои → см. Система плагинов.

#Возможности

Теперь подробно разберём основные функциональные возможности Rspress.

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

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

#Конвенция именования BEM

Все встроенные компоненты теперь используют конвенцию именования BEM. Это позволяет разработчикам гибко настраивать стили с помощью стандартных CSS-селекторов, избегая конфликтов с инструментами вроде Tailwind CSS и значительно снижая порог входа для кастомизации стилей.

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

#Богатые CSS-переменные

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

#Команда rspress eject

Когда возможностей CSS-переменных недостаточно для ваших задач кастомизации, вы можете использовать новую команду rspress eject. Она копирует исходный код встроенных компонентов в директорию темы вашего проекта, позволяя выполнять полную кастомизацию.

# Экспорт компонента навигации в директорию темы
npx rspress eject Nav

#Автоматическая генерация структуры сайта

При создании сайта документации помимо основного контента обычно нужны следующие элементы интерфейса:

• Навигационная панель — глобальное меню сайта.
• Боковое меню (сайдбар) — оглавление раздела.
• Оглавление текущей страницы — структура заголовков статьи.

Оглавление страницы Rspress формирует полностью автоматически: извлекает все заголовки из документа, строит дерево и по умолчанию показывает его справа от текста — никаких дополнительных действий не требуется.

Для навигационной панели и бокового меню предусмотрено два способа настройки (выбирайте любой):

• Декларативная конфигурация — размещение файла _meta.json в нужных папках. Пример:

["introduction", "install", "start"]

Подробности настройки можно найти в разделе Автоматическое формирование навигации.

• Программная конфигурация — задаётся через поля nav и sidebar в файле rspress.config.ts.

В большинстве случаев мы рекомендуем декларативную конфигурацию — она даёт несколько важных преимуществ:

1. Конфигурация получается лаконичнее и понятнее.
2. Структура папок на диске полностью соответствует структуре бокового меню — всё интуитивно понятно.
3. При добавлении/удалении пунктов меню достаточно работать прямо в нужной папке, а не лезть каждый раз в rspress.config.ts, искать нужное место и править там — это сильно снижает переключение контекста.

Программная конфигурация незаменима, когда нужно генерировать навигацию динамически. Например, официальный плагин Rspress TypeDoc автоматически преобразует JSON от TypeDoc в готовые nav и sidebar.

#Поддержка MDX

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

Кроме того, Rspress поддерживает несколько специальных синтаксисов:

• Кастомные контейнеры.
• Метаданные страницы.
• Подсветка строк кода.

Подробности — в разделе Использование MDX.

#Подсветка кода с помощью Shiki

Rspress V2 по умолчанию использует Shiki для подсветки кода. В отличие от решений с подсветкой во время выполнения, Shiki выполняет подсветку на этапе компиляции, обеспечивая точную подсветку синтаксиса, полностью совместимую с VS Code, на основе грамматик TextMate — без дополнительной нагрузки во время выполнения и без увеличения размера бандла.

Цветовые схемы блоков кода можно настраивать через CSS-переменные, а также интерактивно переключать и просматривать различные темы Shiki на странице CSS-переменные.

Shiki также поддерживает расширения через пользовательские трансформеры, что позволяет обогащать текст, например, с помощью twoslash.

#SSG (статическая генерация)

Rspress — это SSG-фреймворк. При продакшен-сборке он автоматически генерирует полностью статический сайт: для каждой страницы создаётся готовый HTML-файл. После завершения сборки эти файлы появляются в папке вывода.

Готовую папку можно развернуть на любом статическом хостинге: GitHub Pages, Netlify, Vercel и т. д.

При необходимости HTML легко кастомизировать — см. Генерация статического сайта.

#Интернационализация (i18n)

Интернационализация — частое требование для сайтов документации. В Rspress она реализована максимально просто и удобно. Мы свели все задачи i18n к четырём вопросам:

• Где хранить переводы?
• Как настроить сайт для разных языков?
• Как организовать папки с разными языковыми версиями?
• Как использовать переводы в собственных компонентах?

Rspress V2 включает встроенные переводы для китайского, английского, японского, корейского и других языков, и в будущем их станет ещё больше. Система автоматически выполняет «Tree Shaking» («встряхивание дерева») на основе конфигурации языка и использования, включая в сборку только необходимый текст. Вы также можете легко расширять или переопределять переводы с помощью опции i18nSource.

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

#Документация нескольких версий

Иногда нужно вести документацию для разных версий продукта. В Rspress поддержка мультиверсионности встроена и включается парой строк конфигурации. При этом структура папок остаётся привычной — никаких вложенностей и новых понятий, без лишних сложностей:

// файл конфигурации
import { defineConfig } from '@rspress/core';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

// Структура директорий
docs
├── v1
│   ├── README.md
│   └── guide
│       └── README.md
└── v2
    ├── README.md
    └── guide

#Полнотекстовый поиск

Rspress предоставляет полнотекстовый поиск «из коробки» — без единой строки конфигурации. Он построен на открытом движке FlexSearch и работает так:

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

Rspress поддерживает два способа настройки темы:

1. Расширение стандартной темы. Во всех компонентах дефолтной темы предусмотрены слоты, через которые можно добавить собственные элементы интерфейса. Пример:

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

const Layout = () => <BasicLayout beforeNavTitle={<p>Custom Block</p>} />;

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

2. Полностью настраиваемая тема. Если нужно написать тему с нуля, вы можете переопределить компонент Layout и использовать предоставляемые Rspress Runtime API (например, usePageData), чтобы получать данные страницы, информацию о маршрутах и т. д.

Подробно о кастомизации темы — в разделе Кастомная тема.

#Система плагинов

Система плагинов — одна из ключевых возможностей Rspress. Она позволяет легко расширять функциональность при сборке сайта. Подробности — в разделе Введение в плагины.

#Документация компонентов

#Превью демо

Rspress предоставляет официальный плагин preview, который автоматически генерирует превью компонентов. После подключения плагина достаточно добавить в MDX-файле такой блок кода:

import React from 'react';
import { Tag, Space } from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';
const COLORS = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'arcoblue',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
];

export default () => {
  return (
    <Space>
      {COLORS.map((color, i) => (
        <Tag key={i} color={color}>
          {color}
        </Tag>
      ))}
    </Space>
  );
};

Тогда в документации появится такое превью:

Конечно, плагин поддерживает и мобильный режим превью — его можно включить в конфигурации:

#Интерактивная песочница в реальном времени

Для документации компонентов возможность редактировать код прямо на странице сильно повышает интерактивность.

Для этого достаточно подключить официальный плагин playground и объявить тот же блок кода в .mdx-файле (как в примере выше).

В результате вы получите вот такую песочницу прямо в документации:

#Встроенные плавные переходы между страницами

Современные браузеры предоставляют нативный View Transition API для анимаций при смене страниц. В Rspress мы сразу подхватили эту возможность: переходы между страницами реализованы именно через View Transition, без каких-либо сторонних SPA-библиотек анимации. В дальнейшем планируем добавить ещё больше эффектов, чтобы сделать навигацию ещё приятнее.

export default defineConfig({
  themeConfig: {
    // Включаем анимацию View Transition
    enableContentAnimation: true,
    enableAppearanceAnimation: true,
  },
});

#Чем Rspress отличается от других SSG-фреймворков

#Отличия от Docusaurus

Docusaurus — открытый SSG-фреймворк от Meta. Как и Rspress, он использует React и поддерживает MDX. Основные отличия:

1. Rspress обеспечивает лучшую производительность сборки благодаря ленивой компиляции и постоянному кэшу, позволяя запускать проект почти мгновенно (холодный старт за миллисекунды). Подробности см. в разделе Производительность сборки.

2. У Rspress проще конфигурация и ниже порог входа. Мы стараемся не вводить лишних концепций и максимально снизить когнитивную нагрузку. Например, поиск работает «из коробки», мультиверсионность интуитивна и т. д.

3. Rspress предоставляет более высокоуровневую абстракцию над бандлером. Конфиги webpack/Rspack сложны и запутанны. Docusaurus передаёт их напрямую пользователю, а Rspress скрывает низкоуровневые детали и предлагает удобные обёртки. Например, добавить теги в <head> можно одной строкой builderConfig.html.tags, без подключения html-webpack-plugin и прочих плагинов.

#Отличия от Nextra

Nextra — открытый SSG-фреймворк от Vercel. Он тоже построен на React и поддерживает MDX. Главные отличия:

1. У Rspress выше производительность сборки (см. отличия от Docusaurus).
2. Rspress легче и «чище». Nextra построен поверх Next.js, поэтому даже в режиме SSG генерирует не только HTML, но и runtime-код Next.js. В результате размер выходных файлов больше, а деплоить нужно как приложение (next start), а не как чистую статику. Rspress не привязан к какому-либо фреймворку — выводит лёгкие чистые HTML-файлы, которые можно развернуть где угодно.

#Отличия от VitePress

VitePress — генератор статических сайтов на базе Vite, использует Vue и обладает отличной производительностью. Основные отличия:

1. Rspress использует React, VitePress — Vue.
2. Rspress работает с MDX, VitePress — с обычным Markdown + Vue-компонентами внутри. Это приводит к разным цепочкам компиляции.
3. На этапе разработки оба стартуют очень быстро. Но в продакшене VitePress использует Rollup для бандлинга, поэтому сталкивается с типичными ограничениями JS-инструментов. Rspress на основе Rspack (Rust) собирает продакшен-сборку ощутимо быстрее.

#Попробуйте Rspress

Перейдите в раздел Быстрый старт, чтобы за несколько минут собрать свой первый сайт документации.