API плагинов

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

globalStyles

Тип: string | string[]

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

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'),
  };
}

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

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])[]

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

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 может быть либо строкой с путём к файлу компонента, либо кортежем. В случае кортежа первый элемент — путь к файлу компонента, а второй — пропсы компонента. Например:

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

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

compUi.tsx

import React from 'react';

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

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

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

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 в качестве инструмента сборки. Настройте Rsbuild с помощью builderConfig. Описание доступных параметров конфигурации см. в документации Rsbuild.

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

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
        },
      },
    },
  };
}

Подробности см. в разделе Конфигурация сборки.

config

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

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

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

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

plugin.ts

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

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

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

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>

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

plugin.ts

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

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

Подсказка

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

markdown

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

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

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>

plugin.ts

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

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

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

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 имеет следующий вид:

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

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

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>

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

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

Пример:

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, чтобы передавать информацию, известную только на этапе сборки, в документацию:

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-компоненте:

import myData from 'virtual-foo';

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

Совет

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

i18nSource

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

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

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

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

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

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

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 для чтения этих текстов:

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

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

#API плагинов

#globalStyles

#globalUIComponents

#builderConfig

#config

#beforeBuild/afterBuild

#markdown

#extendPageData

#addPages

#routeGenerated

#addRuntimeModules

#i18nSource

API плагинов

globalStyles

globalUIComponents

builderConfig

config

beforeBuild/afterBuild

markdown

extendPageData

addPages

routeGenerated

addRuntimeModules

i18nSource