#Кастомная тема

1. Для CSS Rspress предоставляет CSS-переменные и BEM-классы для кастомизации.

2. Для JS / React Rspress реализует runtime-интерфейс на основе ESM re-exports, который поддерживает модификацию или замену встроенных компонентов для реализации собственной домашней страницы, боковой панели, компонентов поиска и т. д.

   На этой основе существуют два режима:

   • wrap: Оборачивать и улучшать встроенные компоненты Rspress через пропсы и слоты.
   • eject: Полностью переопределить весь компонент. Вы можете использовать команду rspress eject, чтобы скопировать исходный код локально и изменить его напрямую.

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

#CSS-переменные

Rspress предоставляет некоторые часто используемые CSS-переменные. По сравнению с переписыванием встроенных React-компонентов Rspress, переопределение CSS-переменных для кастомизации проще и легче в поддержке. Вы можете просмотреть эти CSS-переменные на странице UI - CSS-переменные и переопределить их через:

├── docs
│   └── index.mdx
├── theme
│   ├── index.tsx
│   └── index.css  <-- Скопируйте код CSS-переменных сюда для переопределения стилей
└── rspress.config.ts

import './index.css';
export * from '@rspress/core/theme-original';

Другой подход — использовать конфигурацию globalStyles в файле rspress.config.ts:

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

export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/index.css'), // Указывает на ваш CSS-файл
});

#BEM-классы

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

.rp-[component-name]__[element-name]--[modifier-name] {
  /* стили */
}

Например:

.rp-nav {
}
.rp-link {
}
.rp-tabs {
}
.rp-codeblock {
}
.rp-codeblock__title {
}
.rp-codeblock__description {
}
.rp-nav-menu__item,
.rp-nav-menu__item--active {
}

#Переопределение встроенных компонентов с использованием повторного экспорта ESM

По умолчанию необходимо создать директорию theme в корне проекта, а затем создать в ней файл index.ts или index.tsx. Этот файл используется для экспорта компонентов темы.

├── docs
├── theme
│   └── index.tsx
└── rspress.config.ts

Вы можете написать файл theme/index.tsx, используя встроенные компоненты из @rspress/core/theme-original:

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

При переопределении встроенных компонентов через повторный экспорт ESM все внутренние ссылки Rspress на встроенные компоненты будут преимущественно использовать вашу переэкспортированную версию.

├── docs
│   └── index.mdx <-- используйте "@rspress/core/theme"
├── theme
│   └── index.tsx <-- используйте "@rspress/core/theme-original"
└── rspress.config.ts

#Wrap: Передача пропсов и слотов

Wrap означает добавление пропсов к переэкспортируемым компонентам. Вот пример вставки некоторого содержимого перед заголовком панели навигации:

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

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

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

{
  "some content": {
    "en": "some content",
    "ru": "некий контент"
  }
}

#Eject: Полное переопределение компонента

Eject означает прямое переопределение одного встроенного компонента Rspress, используя полностью вашу собственную версию. Для этого Rspress предоставляет команду rspress eject [component], чтобы скопировать исходный код встроенных компонентов локально и изменить их напрямую. Шаги следующие:

1. Выполните CLI-команду, Rspress извлечет исходный код указанного компонента в локальную директорию theme/components, не извлекая зависимости.

2. Обновите re-export в theme/index.tsx:

// Предположим, что вы выполнили eject компонента DocFooter
export { DocFooter } from './components/DocFooter';
export * from '@rspress/core/theme-original';

3. Измените файл theme/components/DocFooter.tsx по мере необходимости, чтобы удовлетворить вашим требованиям.

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