#Введение

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

#Почему Rspress

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для кастомных компонентов можно также использовать import.meta.env.SSG_MD для вывода обычного текста, дружелюбного к ИИ, в режиме SSG-MD, что позволяет сочетать интерактивный UX с более качественной статической информацией.

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

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

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

#Тема по умолчанию и кастомизация

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

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

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

Тема по умолчанию содержит дополнительные CSS-переменные для цветов темы, блоков кода, компонентов главной страницы и многого другого. Все встроенные компоненты также следуют соглашению об именовании BEM, что упрощает переопределение стилей стандартными CSS-селекторами. Если CSS недостаточно, можно пойти глубже, переопределив встроенные компоненты через ESM-переэкспорт в theme/index.tsx.

#Команда rspress eject

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

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

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

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

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

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

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

Оглавление страницы 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 по умолчанию использует Shiki для подсветки кода. В отличие от решений с подсветкой во время выполнения, Shiki выполняет подсветку на этапе компиляции, обеспечивая точную подсветку синтаксиса, полностью совместимую с VS Code, на основе грамматик TextMate — без дополнительной нагрузки во время выполнения и без увеличения размера бандла.

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

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

#Удобство написания документации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 предоставляет предпросмотр компонентов и редактирование в реальном времени через @rspress/plugin-preview и @rspress/plugin-playground, что хорошо подходит для документации библиотек компонентов и интерактивных примеров.

#Предпросмотр демо библиотеки компонентов

Используйте синтаксис ```tsx preview в mdx-файлах:

```tsx preview
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;
```

Результат рендеринга выглядит следующим образом:

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-preview.

#Интерактивная площадка для библиотеки компонентов

Используйте синтаксис ```tsx playground в mdx-файлах:

```tsx playground
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;
```

Результат рендеринга выглядит следующим образом:

Для режима предпросмотра iframe, направления макета и объединения с preview см. @rspress/plugin-playground.

#Чем 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

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