> 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-custom-theme`](https://github.com/rstackjs/agent-skills#rspress-custom-theme), чтобы он мог помочь вам сгенерировать новую тему с нуля.
Дополнительную информацию о разработке с помощью ИИ в Rspress см. на [странице ИИ](/rspress-russian/guide/start/ai.md).

1. Для CSS Rspress предоставляет [CSS-переменные](#css-variables) и [BEM-классы](#bem-classname) для настройки.

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

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

   - [**wrap**](#wrap): **Обернуть** и расширить встроенные компоненты Rspress с помощью пропсов или слотов.
   - [**eject**](#eject): Полностью **переопределить** компонент. Для этого можно использовать команду [`rspress eject`](/rspress-russian/api/commands.md#rspress-eject), чтобы скопировать исходный код локально и изменить его напрямую.

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

## CSS-переменные \{#css-variables}

Rspress предоставляет набор часто используемых CSS-переменных. По сравнению с переопределением встроенных React-компонентов, изменение CSS-переменных проще и легче в сопровождении. Ознакомиться с ними можно на странице [UI - CSS-переменные](/rspress-russian/ui/vars.md), после чего переопределить их следующим образом:

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

```tsx title="theme/index.tsx"
import './index.css';
export * from '@rspress/core/theme-original';
```

Другой подход — использовать конфигурацию [globalStyles](/rspress-russian/api/config/config-basic.md#globalstyles) в файле `rspress.config.ts`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

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

## BEM-классы \{#bem-classname}

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

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

Например:

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

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

Создайте директорию `theme` в корне проекта, затем создайте в ней файл `index.ts` или `index.tsx` для экспорта компонентов темы.

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

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

```tsx title="theme/index.tsx"
import { Layout as BasicLayout } from '@rspress/core/theme-original';

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

export { Layout }; //[!code highlight]
export * from '@rspress/core/theme-original'; //[!code highlight]
```

Когда вы переопределяете встроенные компоненты с помощью **повторного экспорта ESM**, внутренние ссылки Rspress на эти компоненты в первую очередь используют вашу переопределённую версию.

:::note О @rspress/core/theme-original

`@rspress/core/theme-original` позволяет избежать циклических зависимостей. Используйте его только при настройке темы.

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

1. В директории `docs` используйте `@rspress/core/theme`, который указывает на ваш `theme/index.tsx`.

2. В директории `theme` используйте `@rspress/core/theme-original`, который всегда указывает на встроенные компоненты темы Rspress.

:::

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

Обёртывание означает добавление пропсов к повторно экспортируемым компонентам. Ниже приведён пример, который вставляет содержимое перед заголовком навигационной панели:


**theme/index.tsx**

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


**i18n.json**

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


:::tip

Компонент [`Layout`](/rspress-russian/ui/layout-components/layout.md) разработан с использованием ряда слот-пропсов, специально предназначенных для обёртки. Вы можете использовать эти пропсы для расширения макета темы по умолчанию. Нажмите ниже, чтобы просмотреть расположение слотов на этой странице.


:::

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

Извлечение означает полную замену встроенного компонента Rspress собственной реализацией. Для этого Rspress предоставляет команду [`rspress eject [component]`](/rspress-russian/api/commands.md#rspress-eject), которая копирует исходный код встроенного компонента в локальный проект, чтобы его можно было изменять напрямую.

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

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

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

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

Компоненты Rspress разделены на небольшие независимые части, чтобы сделать извлечение более удобным. Список компонентов, которые можно извлечь, см. в разделе [Компоненты макета](/rspress-russian/ui/layout-components/index.md).

:::warning А нужно ли извлечение?

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

Сначала проверьте, достаточно ли вам обёртывания. Используйте извлечение только в тех случаях, когда обёртывания недостаточно.

:::
