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

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

2. Для JS / React Rspress предоставляет runtime-интерфейс на основе повторного экспорта ESM, позволяющий изменять или заменять встроенные компоненты: главную страницу, боковую панель, компоненты поиска и многое другое.

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

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

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

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

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

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 для экспорта компонентов темы.

Вы можете написать файл 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 на эти компоненты в первую очередь используют вашу переопределённую версию.

#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: Полное переопределение компонента

Извлечение означает полную замену встроенного компонента 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 по мере необходимости, чтобы удовлетворить вашим требованиям.

Компоненты Rspress разделены на небольшие независимые части, чтобы сделать извлечение более удобным. Список компонентов, которые можно извлечь, см. в разделе Компоненты макета.