#Введение

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

#Почему Rspress

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

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

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

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

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

Мы начали с простого вопроса: может ли 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.

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 re-export в theme/index.tsx.

#Команда rspress eject

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

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

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

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

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

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

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

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

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

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

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

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

• Программная конфигурация. Укажите nav и sidebar напрямую в конфигурации Rspress.

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

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.

Rspress также предоставляет конфигурацию для кастомизации HTML, генерируемого SSG. Подробности см. в разделе Генерация статического сайта.

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

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

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

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

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

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

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

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

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

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

Rspress предоставляет полнотекстовый поиск «из коробки», без необходимости дополнительной настройки. Он основан на open-source движке 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 и используйте runtime API Rspress, такие как 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-пайплайн основан на Next.js. Поэтому его результат не является «чистым» HTML — он также включает runtime-код Next.js. Это увеличивает размер выходных файлов и обычно требует развёртывания как приложения с next start, а не как полностью статического сайта. Rspress не привязан к application-фреймворку, поэтому его выходные данные легче и могут быть развернуты как чистый статический сайт.

#Отличия от VitePress

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

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

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

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