> 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.

# API плагинов

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

### globalStyles

- **Тип**: `string | string[]`

Добавляет глобальный файл стилей. Передайте абсолютный путь к файлу стилей:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';
import path from 'path';

export function pluginForDoc(): RspressPlugin {
  // путь к файлу стилей
  const stylePath = path.join(__dirname, 'some-style.css');
  return {
    // имя плагина
    name: 'plugin-name',
    globalStyles: path.join(__dirname, 'global.css'),
  };
}
```

Например, если вы хотите изменить основной цвет темы, это можно сделать, подключив глобальный стиль:

```css title="global.css"
:root {
  --rp-c-brand: #ffa500;
  --rp-c-brand-dark: #ffa500;
  --rp-c-brand-darker: #c26c1d;
  --rp-c-brand-light: #f2a65a;
  --rp-c-brand-lighter: #f2a65a;
}
```

### globalUIComponents

- **Тип**: `(string | [string, object])[]`

Добавляет глобальные компоненты. Передайте массив, в котором каждый элемент — абсолютный путь к компоненту:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  // путь к компоненту
  const componentPath = path.join(__dirname, 'foo.tsx');
  return {
    // имя плагина
    name: 'plugin-comp',
    // путь к глобальным компонентам
    globalUIComponents: [componentPath],
  };
}
```

Каждый элемент `globalUIComponents` может быть либо строкой с путём к файлу компонента, либо кортежем. В случае кортежа первый элемент — путь к файлу компонента, а второй — пропсы компонента. Например:

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

export function pluginForDoc(): RspressPlugin {
  // путь к компоненту
  const componentPath = path.join(__dirname, 'foo.tsx');
  return {
    // имя плагина
    name: 'plugin-comp',
    globalUIComponents: [
      [
        path.join(__dirname, 'components', 'MyComponent.tsx'),
        {
          foo: 'bar',
        },
      ],
    ],
  };
}
```

При регистрации глобальных компонентов Rspress автоматически рендерит эти React-компоненты в теме без необходимости их ручного импорта.

Глобальные компоненты могут реализовывать различные пользовательские функции, такие как:

```tsx title="compUi.tsx"
import React from 'react';

// Необходим экспорт по умолчанию
// Пропсы приходят из вашей конфигурации
export default function PluginUI(props?: { foo: string }) {
  return <div>Это глобальный компонент макета</div>;
}
```

Содержимое компонента затем рендерится в теме, например для добавления кнопки **BackToTop**.

Также глобальный компонент можно использовать для регистрации побочных эффектов:

```tsx title="compSideEffect.tsx"
import { useEffect } from 'react';
import { useLocation } from '@rspress/core/runtime';

// Необходим экспорт по умолчанию
export default function PluginSideEffect() {
  const { pathname } = useLocation();
  useEffect(() => {
    // Выполняется при первом рендере компонента
  }, []);

  useEffect(() => {
    // Выполняется при изменении маршрута
  }, [pathname]);
  return null;
}
```

Побочные эффекты компонента затем выполняются в теме. Например, они полезны для:

- Перенаправления определённых маршрутов страниц.
- Привязки событий клика к тегам `img` на странице для реализации увеличения изображений.
- Отправки данных о просмотрах страниц при изменении маршрута.

### builderConfig

- **Тип**: `RsbuildConfig`

Rspress использует [Rsbuild](https://github.com/web-infra-dev/rsbuild) в качестве инструмента сборки. Настройте Rsbuild с помощью `builderConfig`. Описание доступных параметров конфигурации см. в документации [Rsbuild](https://rsbuild.rs/config/).

> Чтобы настроить Rspack напрямую, используйте `builderConfig.tools.rspack`.

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(slug: string): RspressPlugin {
  return {
    name: 'plugin-name',
    // Определение глобальных переменных на этапе сборки
    builderConfig: {
      source: {
        define: {
          SLUG: JSON.stringify(slug),
        },
      },
      tools: {
        rspack(options) {
          // Изменение конфигурации rspack
        },
      },
    },
  };
}
```

> Подробности см. в разделе [Конфигурация сборки](/rspress-russian/api/config/config-build.md).

### config

- **Тип**: `(config: DocConfig, utils: ConfigUtils) => DocConfig | Promise<DocConfig>`

Тип `ConfigUtils` выглядит следующим образом:

```ts
interface ConfigUtils {
  addPlugin: (plugin: RspressPlugin) => void;
  removePlugin: (pluginName: string) => void;
}
```

Изменяет или расширяет конфигурацию самого Rspress. Например, с помощью `config` можно изменить заголовок сайта:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    // Имя плагина
    name: 'plugin-name',
    // Расширение/изменение конфигурации Rspress
    config(config) {
      return {
        ...config,
        title: 'Новый заголовок',
      };
    },
  };
}
```

Для добавления или удаления плагинов используйте `addPlugin` и `removePlugin`:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    // Имя плагина
    name: 'plugin-name',
    // Расширение/изменение конфигурации Rspress
    config(config, utils) {
      // Добавление плагина
      utils.addPlugin({
        name: 'plugin-name',
        // ... Остальные настройки плагина
      });
      // Удаление плагина — передайте имя плагина
      utils.removePlugin('plugin-name');
      return config;
    },
  };
}
```

### beforeBuild/afterBuild

- **Тип**: `(config: DocConfig, isProd: boolean) => void | Promise<void>`

Выполняет операции до или после сборки документации. Первый параметр — разрешённая конфигурация документации, второй указывает, запущена ли сборка в продакшен-режиме:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    name: 'plugin-name',
    // Хук, выполняемый до начала сборки
    async beforeBuild(config, isProd) {
      // Выполните здесь нужные действия
    },
    // Хук, выполняемый после завершения сборки
    async afterBuild(config, isProd) {
      // Выполните здесь нужные действия
    },
  };
}
```

:::tip Подсказка
К моменту выполнения `beforeBuild` уже обработаны все хуки `config` всех плагинов, поэтому параметр `config` содержит итоговую конфигурацию документации.
:::

### markdown

- **Тип**: `{ remarkPlugins?: Plugin[]; rehypePlugins?: Plugin[] }`

Расширяет процесс компиляции Markdown/MDX. Используйте `markdown`, чтобы добавить собственные плагины remark/rehype или глобальные компоненты MDX (`globalComponents`):

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    name: 'plugin-name',
    markdown: {
      remarkPlugins: [
        // Добавляем свои remark-плагины
      ],
      rehypePlugins: [
        // Добавляем свои rehype-плагины
      ],
      globalComponents: [
        // Регистрируем глобальные компоненты, доступные внутри MDX
      ],
    },
  };
}
```

### extendPageData

- **Тип**: `(pageData: PageData) => void | Promise<void>`

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    name: 'plugin-name',
    // Расширяем данные страницы
    extendPageData(pageData, isProd) {
      // Добавляем или изменяем свойства объекта pageData
      pageData.a = 1;
    },
  };
}
```

После расширения данных страницы вы сможете получить эти данные в теме через хук `usePageData`.

```tsx
import { usePageData } from '@rspress/core/runtime';

export function MyComponent() {
  const { page } = usePageData();
  // page.a === 1
  return <div>{page.a}</div>;
}
```

### addPages

- **Тип**: `(config: UserConfig) => AdditionalPage[] | Promise<AdditionalPage[]>`

Параметр `config` — это конфигурация документации из `rspress.config.ts`, а тип `AdditionalPage` имеет следующий вид:

```tsx
interface AdditionalPage {
  routePath: string;
  filepath?: string;
  content?: string;
}
```

Добавляет дополнительные страницы. Верните массив из `addPages`, где каждый элемент — это конфигурация страницы. Используйте `routePath` для указания маршрута страницы, а `filepath` или `content` — для задания содержимого страницы. Например:

```tsx
import path from 'path';
import type { RspressPlugin } from '@rspress/core';

export function docPluginDemo(): RspressPlugin {
  return {
    name: 'add-pages',
    addPages(config, isProd) {
      return [
        // Поддерживает абсолютный путь к реальному файлу (`filepath`) и считывает md(x)-содержимое с диска
        {
          routePath: '/filepath-route',
          filepath: path.join(__dirname, 'blog', 'index.md'),
        },
        // Поддерживает прямую передачу md(x)-содержимого через параметр `content`
        {
          routePath: '/content-route',
          content: '# Demo2',
        },
      ];
    },
  };
}
```

`addPages` принимает два параметра: `config` — это текущая конфигурация сайта документации, а `isProd` указывает, запущена ли сборка в продакшен-режиме.

### routeGenerated

- **Тип**：`(routeMeta: RouteMeta[]) => void | Promise<void>`

Этот хук получает все метаданные маршрутов. Каждый элемент метаданных маршрута имеет следующую структуру:

```ts
export interface RouteMeta {
  // путь маршрута
  routePath: string;
  // абсолютный путь к файлу на диске
  absolutePath: string;
  // имя страницы, используется в имени чанка при сборке
  pageName: string;
  // язык текущего маршрута
  lang: string;
}
```

Пример:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    // Имя плагина
    name: 'plugin-routes',
    // Хук, выполняемый после генерации всех маршрутов
    async routeGenerated(routes, isProd) {
      // Выполните здесь нужные действия
    },
  };
}
```

### addRuntimeModules

- **Тип**: `(config: UserConfig, isProd: boolean) => Record<string, string> | Promise<Record<string, string>>;`

Добавляет дополнительные runtime-модули. Например, используйте `addRuntimeModules`, чтобы передавать информацию, известную только на этапе сборки, в документацию:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    // Имя плагина
    name: 'plugin-name',
    // Добавление дополнительных runtime-модулей
    async addRuntimeModules(config, isProd) {
      const fetchSomeData = async () => {
        // Имитация асинхронного запроса
        return { a: 1 };
      };
      const data = await fetchSomeData();
      return {
        'virtual-foo': `export default ${JSON.stringify(data)}`,
      };
    },
  };
}
```

Затем вы можете использовать модуль `virtual-foo` в runtime-компоненте:

```jsx
import myData from 'virtual-foo';

export function MyComponent() {
  return <div>{myData.a}</div>;
}
```

:::tip

Этот хук выполняется **после** хука `routeGenerated`.

:::

### i18nSource

- **Тип**: `(source: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>>`

Добавляет или изменяет данные интернационализации (i18n). Используйте этот хук для расширения или переопределения текстов i18n в теме.

Параметр `source` — это объект следующей структуры:

```ts
{
  [textKey: string]: {
    [locale: string]: string;
  }
}
```

Ключ первого уровня `textKey` — это ключ текста, второй уровень `locale` — код языка (например, `ru` или `en`), а значение — это перевод для соответствующего языка.

Пример использования:

```tsx title="plugin.ts"
import type { RspressPlugin } from '@rspress/core';

export function pluginForDoc(): RspressPlugin {
  return {
    // Имя плагина
    name: 'plugin-name',
    // Добавляем или изменяем строки i18n
    i18nSource(source) {
      // Добавляем новые строки
      return {
        ...source,
        customKey: {
          zh: '自定义文案',
          en: 'Custom Text',
          ru: 'Свой текст',
        },
        anotherKey: {
          zh: '另一个文案',
          en: 'Another Text',
          ru: 'Другой текст',
        },
      };
    },
  };
}
```

Если ваш плагин также предоставляет runtime-компоненты, используйте хук `useI18n` для чтения этих текстов:

```tsx
import { useI18n } from '@rspress/core/runtime';

export function MyComponent() {
  const t = useI18n();
  return <div>{t('customKey')}</div>;
}
```
