> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# Введение

Rspress — это генератор статических сайтов на базе React, построенный на [Rsbuild](https://rsbuild.rs/). Он поставляется с темой документации по умолчанию, поэтому вы можете быстро создать сайт документации, адаптировать тему для блогов или главных страниц продуктов, а также использовать официальные плагины для документации библиотек компонентов.

## Почему Rspress

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

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

Эти пункты также являются ключевыми требованиями для разработки статических сайтов. В следующих разделах они рассматриваются подробно.

### Производительность сборки \{#build-performance}

По мере роста проектов длительное время запуска становится серьёзным тормозом разработки. Чем дольше живёт проект, тем заметнее становится эта проблема.

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

Rspress был создан, чтобы ответить на этот вопрос.

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

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

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

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

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

Rspress предоставляет возможность **SSG-MD**, которая рендерит страницы в виде Markdown-файлов вместо HTML и генерирует индексные файлы, соответствующие спецификации [llms.txt](https://llmstxt.org/).

```ts title="rspress.config.ts"
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-russian/guide/basic/ssg-md.md).

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

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

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

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

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

Дефолтная тема предоставляет CSS-переменные для цветов темы, блоков кода, компонентов главной страницы и других элементов. Все встроенные компоненты следуют [BEM-неймингу](https://getbem.com/), что упрощает переопределение стилей с помощью стандартных CSS-селекторов. Если возможностей CSS недостаточно, можно переопределять встроенные компоненты через ESM re-export в `theme/index.tsx`.

#### Команда `rspress eject`

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

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

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

Rspress предоставляет [компонент Tag](/rspress-russian/ui/layout-components/tag.md). Вы можете определить `tag` в метаданных и отображать эти аннотации в заголовках, навигационной панели, боковом меню и оглавлении.

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

Большинству сайтов документации, помимо основного контента, требуются следующие модули макета:

- Панель — глобальное меню сайта.
- Сайдбар — оглавление раздела.
- Оглавление — структура заголовков текущей страницы.

Для оглавления Rspress автоматически извлекает заголовки текущей страницы и отображает их справа по умолчанию.

Для панели навигации и сайдбара Rspress поддерживает два способа конфигурации:

- **Декларативная конфигурация**. Настройка данных через файл `_meta.json` в директории:

```json title="_meta.json"
["introduction", "install", "start"]
```

Подробности настройки можно найти в разделе [Автонавигация](/rspress-russian/guide/basic/auto-nav-sidebar.md).

- **Программная конфигурация**. Укажите [nav](/rspress-russian/api/config/config-theme.md#nav) и [sidebar](/rspress-russian/api/config/config-theme.md#sidebar) напрямую в конфигурации Rspress.

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

1. Делает файл конфигурации более компактным.
2. Делает связь между структурой файлов и структурой сайдбара более интуитивной.
3. Позволяет добавлять или удалять элементы сайдбара прямо в текущей директории, не возвращаясь к `rspress.config.ts`.

Программная конфигурация полезна, когда навигацию нужно генерировать динамически. Например, официальный плагин Rspress [TypeDoc](/rspress-russian/plugin/official-plugins/typedoc.md) преобразует JSON-данные TypeDoc в конфигурации `nav` и `sidebar`.

### Поддержка MDX

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

![](https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/rspress/mdx-intro.png)
Кроме того, Rspress поддерживает несколько специальных синтаксисов:

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

Подробности — в разделе [Использование MDX](/rspress-russian/guide/use-mdx/components.md).

### Подсветка кода с помощью [Shiki](https://shiki.style/)

Rspress по умолчанию использует [Shiki](https://shiki.style/) для подсветки кода. В отличие от решений с подсветкой во время выполнения, Shiki выполняет подсветку на этапе компиляции, обеспечивая точную подсветку синтаксиса, полностью совместимую с VS Code, на основе грамматик TextMate — без дополнительной нагрузки во время выполнения и без увеличения размера бандла.

Цветовые схемы блоков кода можно настраивать через CSS-переменные, а также интерактивно переключать и просматривать различные темы Shiki на странице [CSS-переменные](/rspress-russian/ui/vars.md). Shiki также поддерживает расширения через пользовательские [трансформеры](https://shiki.style/guide/transformers), что позволяет обогащать текст, например, с помощью [twoslash](https://twoslash.netlify.app/).

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

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

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

Конкретные примеры `preview` и `playground` см. в разделе [Документация компонентов](#component-documentation) ниже.

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

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

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

Rspress также предоставляет конфигурацию для кастомизации HTML, генерируемого SSG. Подробности см. в разделе [Генерация статического сайта](/rspress-russian/guide/basic/ssg.md).

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

Интернационализация (i18n) часто используется в сайтах документации. Rspress упрощает работу с i18n, структурируя её вокруг следующих задач:

- Определение источника i18n-данных.
- Настройка сайта для каждого языка.
- Организация документации для разных языков.
- Использование i18n-текста в пользовательских компонентах.

Rspress включает встроенные переводы для китайского, английского, японского, корейского и других языков, и список будет расширяться. Система выполняет tree-shaking языковых строк на основе конфигурации и использования, включая в сборку только необходимое. Вы также можете расширять или переопределять переводы через [`i18nSource`](/rspress-russian/api/config/config-basic.md#i18nsource).

Вы можете следовать [руководству по I18n](/rspress-russian/guide/basic/i18n.md), чтобы пошагово реализовать интернационализацию для вашего сайта.

### Мультиверсионность

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

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

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

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

### Полнотекстовый поиск \{#full-text-search}

Rspress предоставляет полнотекстовый поиск «из коробки», без необходимости дополнительной настройки. Он основан на open-source движке FlexSearch:

![Результаты полнотекстового поиска Rspress v2](https://assets.rspack.rs/rspress/assets/rspress-full-text-search.png)
### Кастомизация темы

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

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

```tsx
// 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` и используйте runtime API Rspress, такие как `usePageData`, чтобы получать данные, доступные на этапе сборки, информацию о маршрутизации и многое другое.

Подробно о кастомизации темы — в разделе [Кастомная тема](/rspress-russian/guide/basic/custom-theme.md).

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

Система плагинов — это ключевая часть Rspress, которая позволяет расширять поведение сборки сайта. Подробности см. в разделе [Введение в плагины](/rspress-russian/plugin/system/introduction.md).

### Документация компонентов \{#component-documentation}

Rspress предоставляет предпросмотр компонентов и редактирование в реальном времени через [@rspress/plugin-preview](/rspress-russian/plugin/official-plugins/preview.md) и [@rspress/plugin-playground](/rspress-russian/plugin/official-plugins/playground.md), что хорошо подходит для документации библиотек компонентов и интерактивных примеров.

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

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

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

В результате это отображается следующим образом:

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

Если вы предпочитаете хранить код демо во внешних файлах, вы можете объединить его с блоками кода из файлов. Подробности см. в [@rspress/plugin-preview](/rspress-russian/plugin/official-plugins/preview.md).

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

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

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

В результате это отображается следующим образом:

```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-russian/plugin/official-plugins/playground.md).

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

### Отличия от Docusaurus

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

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

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

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

### Отличия от Nextra

[Nextra](https://nextra.vercel.app/ "Nextra") — открытый SSG-фреймворк от Vercel. Он тоже построен на React и поддерживает MDX. Главные отличия:

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

### Отличия от VitePress

[VitePress](https://vitepress.dev/ "VitePress") — генератор статических сайтов на базе Vite, использует Vue и обладает отличной производительностью. Основные отличия:

1. Rspress использует React, VitePress — Vue.
2. Rspress работает с MDX, VitePress — с обычным Markdown + Vue-компонентами внутри. Это приводит к разным цепочкам компиляции.
3. По производительности сборки: и Rspress, и VitePress быстро запускаются в режиме разработки. В продакшене VitePress использует Rollup для бандлинга и сталкивается с теми же ограничениями производительности, что и другие JavaScript-инструменты. На этом этапе Rspress работает быстрее.

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

Перейдите в раздел [Быстрый старт](/rspress-russian/guide/start/getting-started.md), чтобы за несколько минут собрать свой первый сайт документации.
