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

# Базовая конфигурация

## root

- **Тип**: `string`
- **По умолчанию**: `docs`

Указывает корневой каталог документации. Например:

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

export default defineConfig({
  root: 'docs',
});
```

Эта опция поддерживает как относительные, так и абсолютные пути. Относительные пути разрешаются относительно текущей рабочей директории (`cwd`).

В качестве аргумента командной строки также можно передать корневой каталог документации:

```bash
rspress dev docs
rspress build docs
```

## base

- **Тип**: `string`
- **По умолчанию**: `/`

Базовый путь для развёртывания. Например, если вы планируете разместить сайт по адресу `https://foo.github.io/bar/`, то значение `base` нужно установить в `"/bar/"`:

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

export default defineConfig({
  base: '/bar/',
});
```

## siteOrigin


[Добавлено в v2.0.17](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.17)

- **Тип**: `string`
- **По умолчанию**: `""`

Необязательный базовый URL, по которому развёрнут сайт, например `https://foo.github.io`.

Rspress использует это значение вместе с параметром [`base`](#base), когда при генерации файлов требуются абсолютные URL, например для ссылок в `llms.txt` или данных, создаваемых плагинами. Полный URL формируется в следующем порядке: `siteOrigin + base + routePath`.

Если `siteOrigin` не задан, Rspress использует в качестве альтернативы `base + routePath`.

Если ваш сайт развёрнут по адресу `https://foo.github.io/bar/`, установите `siteOrigin` в `"https://foo.github.io"`, а `base` — в `"/bar/"`:

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

export default defineConfig({
  siteOrigin: 'https://foo.github.io',
  base: '/bar/',
});
```

## title

- **Тип**: `string`
- **По умолчанию**: `"Rspress"`

Название сайта. Rspress использует его в качестве заголовка HTML-страницы. Например:

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

export default defineConfig({
  title: 'My Site',
});
```

## description

- **Тип**: `string`
- **По умолчанию**: `""`

Описание сайта. Rspress использует его в качестве описания HTML-страницы. Например:

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

export default defineConfig({
  description: 'My Site Description',
});
```

## icon

- **Тип**: `string | URL`
- **По умолчанию**: `""`

Иконка сайта. Rspress использует этот путь в качестве иконки HTML-страницы. Например:

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

export default defineConfig({
  icon: '/favicon.ico',
});
```

Для обычного пути Rspress ищет иконку в каталоге `public`. Также можно использовать URL CDN, протокол `file://` или объект `URL`, указывающий на локальный абсолютный путь.

## lang

- **Тип**: `string`
- **По умолчанию**: `"en"`

Язык сайта по умолчанию. Подробности см. в разделе [i18n](/rspress-russian/guide/basic/i18n.md).

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

export default defineConfig({
  lang: 'en',
  locales: [
    {
      lang: 'en',
      // ...
    },
    {
      lang: 'ru',
      // ...
    },
  ],
});
```

## locales

- **Тип**: `Locale[]`
- **По умолчанию**: `undefined`

Настраивает поддерживаемые языки и информацию о сайте для каждого языка.

```ts
export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}
```

| Поле          | Описание                                                                              |
| ------------- | ------------------------------------------------------------------------------------- |
| `lang`        | Код языка. Должен совпадать с именем соответствующей директории в корне документации. |
| `label`       | Отображаемый текст в переключателе языков панели навигации.                           |
| `title`       | Заголовок сайта для этого языка.                                                      |
| `description` | Описание сайта для этого языка.                                                       |

Установите верхнеуровневый параметр [`lang`](#lang) в один из этих кодов языков, чтобы выбрать язык по умолчанию. Rspress опускает языковой префикс в маршрутах языка по умолчанию.

Например:

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

export default defineConfig({
  lang: 'ru',
  locales: [
    {
      lang: 'en',
      label: 'English',
      title: 'My Site',
      description: 'My site description',
    },
    {
      lang: 'ru',
      label: 'Русский',
      title: 'Мой сайт',
      description: 'Описание моего сайта',
    },
  ],
});
```

Полный пример настройки см. в разделе [i18n](/rspress-russian/guide/basic/i18n.md). О языковых параметрах темы, таких как `nav` и `sidebar`, см. в разделе [`themeConfig.locales`](/rspress-russian/api/config/config-theme.md#locales).

## i18nSourcePath

- **Тип**: `string`
- **По умолчанию**: `path.join(cwd, 'i18n.json')`

Указывает путь к файлу источника данных i18n. По умолчанию Rspress читает файл `i18n.json` из текущей рабочей директории. Например:

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

export default defineConfig({
  i18nSourcePath: path.join(__dirname, 'config/i18n.json'),
});
```

:::tip

Это имеет тот же эффект, что и размещение файла `i18n.json` в корне проекта. Если также настроен `i18nSource`, то данные из `i18nSource` будут объединены с данными из `i18nSourcePath` и имеют приоритет.

:::

## i18nSource

- **Тип**: `Record<string, Record<string, string>> | ((value: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>>)`
- **По умолчанию**: `{}`

Используйте этот параметр, чтобы изменить встроенные локализованные строки Rspress или добавить строки для пользовательских компонентов. Обычно он используется вместе с [useI18n](/rspress-russian/ui/hooks/use-i18n.md).

:::tip

Реализация и эффект полностью совпадают с файлом `i18n.json`. Можно использовать любой из этих способов. Параметр `i18nSource` имеет более высокий приоритет, чем `i18n.json`, и поддерживает функции.

:::

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

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

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

Вот пример изменения встроенных i18n-текстов Rspress:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
export default defineConfig({
  i18nSource: {
    editLinkText: {
      en: '📝 Edit this page on Gitlab',
      ru: '📝 Изменить эту страницу на Gitlab',
    },
  },
});
```

`i18nSource` также может быть функцией, например:

```ts
import { defineConfig } from '@rspress/core';

export default defineConfig({
  i18nSource: async source => {
    for (const key of Object.keys(source)) {
      source[key]['en_US'] = source[key]['en'];
    }
    return source;
  },
});
```

Вот встроенные строки i18n в Rspress:


```ts file="<root>/node_modules/@rspress/core/dist/node/runtimeModule/i18n/DEFAULT_I18N_TEXT.js"
const DEFAULT_I18N_TEXT = {
    languagesText: {
        zh: '语言',
        en: 'Languages',
        ja: '言語',
        ko: '언어',
        ru: 'Языки',
        ta: 'மொழிகள்'
    },
    themeText: {
        zh: '主题',
        en: 'Theme',
        ja: 'テーマ',
        ko: '테마',
        ru: 'Тема',
        ta: 'தோற்றம்'
    },
    versionsText: {
        zh: '版本',
        en: 'Versions',
        ja: 'バージョン',
        ko: '버전',
        ru: 'Версии',
        ta: 'பதிப்புகள்'
    },
    menuTitle: {
        zh: '菜单',
        en: 'Menu',
        ja: 'メニュー',
        ko: '사이드바 메뉴',
        ru: 'Меню',
        ta: 'பட்டி'
    },
    outlineTitle: {
        zh: '目录',
        en: 'ON THIS PAGE',
        ja: '目次',
        ko: '이 페이지 목차',
        ru: 'ОГЛАВЛЕНИЕ',
        ta: 'இந்தப் பக்கத்தில்'
    },
    scrollToTopText: {
        en: 'Back to top',
        zh: '回到顶部',
        ja: 'トップに戻る',
        ko: '맨 위로',
        ru: 'Наверх',
        ta: 'பக்கத்தின் மேலே செல்லவும்'
    },
    lastUpdatedText: {
        en: 'Last Updated',
        zh: '最后更新于',
        ja: '最終更新',
        ko: '업데이트 날짜',
        ru: 'Последнее обновление',
        ta: 'கடைசியாகப் புதுப்பிக்கப்பட்டது'
    },
    lastUpdatedAuthorText: {
        en: 'by',
        zh: '作者',
        ja: '更新者',
        ko: '작성자',
        ru: 'автор',
        ta: 'புதுப்பித்தவர்'
    },
    prevPageText: {
        en: 'Previous page',
        zh: '上一页',
        ja: '前のページ',
        ko: '이전 페이지',
        ru: 'Предыдущая страница',
        ta: 'முந்தைய பக்கம்'
    },
    nextPageText: {
        en: 'Next page',
        zh: '下一页',
        ja: '次のページ',
        ko: '다음 페이지',
        ru: 'Следующая страница',
        ta: 'அடுத்த பக்கம்'
    },
    sourceCodeText: {
        en: 'Source Code',
        zh: '源码',
        ja: 'ソースコード',
        ko: '소스 코드',
        ru: 'Исходный код',
        ta: 'மூலக் குறியீடு'
    },
    searchPlaceholderText: {
        en: 'Search',
        zh: '搜索',
        ja: '検索',
        ko: '검색',
        ru: 'Поиск',
        ta: 'தேடுக'
    },
    searchPanelCancelText: {
        en: 'Cancel',
        zh: '取消',
        ja: 'キャンセル',
        ko: '취소',
        ru: 'Отмена',
        ta: 'ரத்து செய்'
    },
    searchNoResultsText: {
        en: 'No matching results',
        zh: '未找到与之匹配的结果',
        ja: '一致する結果が見つかりません',
        ko: '일치하는 결과가 없습니다',
        ru: 'Нет результатов, соответствующих запросу',
        ta: 'பொருந்தும் முடிவுகள் இல்லை'
    },
    searchSuggestedQueryText: {
        en: 'Try searching for different keywords',
        zh: '试试搜索不同关键词',
        ja: '別のキーワードで検索してみてください',
        ko: '다른 키워드로 검색해 보세요',
        ru: 'Попробуйте поискать по другим ключевым словам',
        ta: 'வேறு தேடல் சொற்களை முயற்சிக்கவும்'
    },
    'overview.filterNameText': {
        en: 'Filter',
        zh: '筛选',
        ja: 'フィルター',
        ko: '필터',
        ru: 'Фильтр',
        ta: 'வடிகட்டு'
    },
    'overview.filterPlaceholderText': {
        en: 'Search API',
        zh: '搜索 API',
        ja: 'API を検索',
        ko: 'API 검색',
        ru: 'API поиска',
        ta: 'API-ஐத் தேடுக'
    },
    'overview.filterNoResultText': {
        en: 'No matching API found',
        zh: '未找到匹配的 API',
        ja: '一致する API が見つかりません',
        ko: '일치하는 API가 없습니다',
        ru: 'Не найден подходящий API',
        ta: 'பொருந்தும் API எதுவும் கிடைக்கவில்லை'
    },
    openInText: {
        en: 'Open in {{name}}',
        zh: '在 {{name}} 中打开',
        ja: '{{name}} で開く',
        ko: '{{name}}에서 열기',
        ru: 'Открыть в {{name}}',
        ta: '{{name}}-இல் திறக்கவும்'
    },
    copyMarkdownText: {
        en: 'Copy Markdown',
        zh: '复制 Markdown',
        ja: 'Markdown をコピー',
        ko: '마크다운 복사',
        ru: 'Скопировать Markdown',
        ta: 'Markdown-ஐ நகலெடு'
    },
    copyMarkdownLinkText: {
        en: 'Copy Markdown link',
        zh: '复制 Markdown 链接',
        ja: 'Markdown リンクをコピー',
        ko: '마크다운 링크 복사',
        ru: 'Скопировать ссылку в формате Markdown',
        ta: 'Markdown இணைப்பை நகலெடு'
    },
    editLinkText: {
        en: 'Edit this page',
        zh: '编辑此页面',
        ja: 'このページを編集',
        ko: '이 페이지 편집',
        ru: 'Отредактировать страницу',
        ta: 'இந்தப் பக்கத்தைத் திருத்தவும்'
    },
    codeButtonGroupCopyButtonText: {
        en: 'Copy code',
        zh: '复制代码',
        ja: 'コードをコピー',
        ko: '코드 복사',
        ru: 'Скопировать код',
        ta: 'குறியீட்டை நகலெடு'
    },
    codeButtonGroupWrapButtonText: {
        en: 'Toggle code wrap',
        zh: '切换代码换行',
        ja: 'コードの折り返しを切り替え',
        ko: '코드 줄바꿈 전환',
        ru: 'Переключить перенос кода',
        ta: 'குறியீட்டு வரி மடக்கத்தை மாற்று'
    },
    notFoundText: {
        en: 'PAGE NOT FOUND',
        zh: '页面未找到',
        ja: 'ページが見つかりません',
        ko: '페이지를 찾을 수 없음',
        ru: 'СТРАНИЦА НЕ НАЙДЕНА',
        ta: 'பக்கம் கிடைக்கவில்லை'
    },
    takeMeHomeText: {
        en: 'Take me home',
        zh: '返回首页',
        ja: 'ホームに連れてって',
        ko: '홈으로 이동',
        ru: 'Вернуться на главную',
        ta: 'முகப்புக்குச் செல்லவும்'
    },
    errorTitleText: {
        en: 'Something went wrong',
        zh: '页面出了点问题',
        ja: 'エラーが発生しました',
        ko: '문제가 발생했습니다',
        ru: 'Что-то пошло не так',
        ta: 'பிழை ஏற்பட்டது'
    },
    errorDescriptionText: {
        en: 'This page could not be loaded. Try reloading it or return to the home page.',
        zh: '页面未能正常加载，请尝试重新加载，或返回首页。',
        ja: 'ページを読み込めませんでした。再読み込みするか、ホームに戻ってください。',
        ko: '페이지를 불러올 수 없습니다. 새로고침하거나 홈으로 돌아가세요.',
        ru: 'Не удалось загрузить страницу. Попробуйте обновить её или вернуться на главную.',
        ta: 'இந்தப் பக்கத்தை ஏற்ற முடியவில்லை. மீண்டும் ஏற்றவும் அல்லது முகப்புப் பக்கத்திற்குத் திரும்பவும்.'
    },
    reloadPageText: {
        en: 'Reload page',
        zh: '重新加载',
        ja: '再読み込み',
        ko: '새로고침',
        ru: 'Обновить страницу',
        ta: 'பக்கத்தை மீண்டும் ஏற்றவும்'
    },
    errorDetailsText: {
        en: 'Error details',
        zh: '错误详情',
        ja: 'エラーの詳細',
        ko: '오류 세부 정보',
        ru: 'Подробности ошибки',
        ta: 'பிழை விவரங்கள்'
    },
    promptCopyText: {
        en: 'Copy Prompt',
        zh: '复制 Prompt',
        ja: 'Prompt をコピー',
        ko: '프롬프트 복사',
        ru: 'Скопировать Prompt',
        ta: 'Prompt-ஐ நகலெடு'
    },
    promptCopiedText: {
        en: 'Copied',
        zh: '已复制',
        ja: 'コピーしました',
        ko: '복사됨',
        ru: 'Скопировано',
        ta: 'நகலெடுக்கப்பட்டது'
    },
    promptExpandText: {
        en: 'Expand',
        zh: '展开',
        ja: '展開',
        ko: '펼치기',
        ru: 'Развернуть',
        ta: 'விரிவாக்கு'
    },
    promptCollapseText: {
        en: 'Collapse',
        zh: '折叠',
        ja: '折りたたむ',
        ko: '접기',
        ru: 'Свернуть',
        ta: 'சுருக்கு'
    }
};
export { DEFAULT_I18N_TEXT };

```

## logo \{#logo-1}

- **Тип**: `string | { dark: string; light: string; width?: number; height?: number }`
- **По умолчанию**: `""`

Логотип сайта. Rspress использует его в качестве логотипа в левом верхнем углу панели навигации. В объектной форме необязательные `width` и `height` задают внутренние размеры (в пикселях) для обоих изображений; используйте размеры исходных изображений, чтобы сохранить их соотношение сторон и уменьшить сдвиги макета. Например:

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

export default defineConfig({
  logo: '/logo.png',
});
```

Rspress ищет логотип в каталоге `public`. Также можно использовать URL CDN.

Кроме того, можно задать разные логотипы для светлой и тёмной тем:

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

export default defineConfig({
  logo: {
    dark: '/logo-dark.png',
    light: '/logo-light.png',
    width: 120,
    height: 32,
  },
});
```

## logoHref

- **Тип**: `string`
- **По умолчанию**: `/${lang}/`

Пользовательский ссылка для логотипа. По умолчанию при клике на логотип происходит переход на главную страницу текущего языка. Например:

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

export default defineConfig({
  logo: '/logo.png',
  logoHref: 'https://example.com',
});
```

## logoText

- **Тип**: `string`
- **По умолчанию**: `""`

Текст логотипа сайта. Rspress отображает его в левом верхнем углу панели навигации. Например:

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

export default defineConfig({
  logoText: 'rspress',
});
```

## outDir

- **Тип**: `string`
- **По умолчанию**: `doc_build`

Пользовательская директория для вывода собранного сайта. Например:

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

export default defineConfig({
  outDir: 'doc_build',
});
```

## themeDir

- **Тип**: `string`
- **По умолчанию**: `theme`

Указывает директорию пользовательской темы. По умолчанию Rspress использует директорию `theme` в текущей рабочей директории в качестве директории пользовательской темы. Вы можете использовать `themeDir` для её настройки. Например:

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

export default defineConfig({
  themeDir: path.join(__dirname, 'my-theme'),
});
```

Эта опция поддерживает как относительные, так и абсолютные пути. Относительные пути разрешаются относительно текущей рабочей директории.

Подробнее о пользовательских темах см. [Кастомная тема](/rspress-russian/guide/basic/custom-theme.md).

## head

- **Тип**: `string` | `[string, Record<string, string>]` | `(route) => string | [string, Record<string, string>] | undefined`
- Можно дополнять на отдельной странице через [метаданные](/rspress-russian/api/config/config-frontmatter.md#head)

Добавляет дополнительные элементы в HTML-элемент `<head>` страницы при продакшен-сборке.

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

export default defineConfig({
  // ... другие настройки
  head: [
    '<meta name="author" content="John Doe">',
    // или
    ['meta', { name: 'author', content: 'John Doe' }],
    // [htmlTag, { attrName: attrValue, attrName2: attrValue2 }]
    // или
    route => {
      if (route.routePath.startsWith('/jane/'))
        return "<meta name='author' content='Jane Doe'>";
      if (route.routePath.startsWith('/john/'))
        return ['meta', { name: 'author', content: 'John Doe' }];
      // или вообще ничего не возвращаем
      return undefined;
    },
  ],
});
```

## globalStyles

- **Тип:** `string`
- **По умолчанию:** `undefined`

Добавляет глобальные стили из указанного файла стилей. Например:

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

export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/global.css'),
});
```

```css title="styles/global.css"
:root {
  --rp-c-brand: #f00;
}
```

## sitemap


[Добавлено в v2.1.0](https://github.com/web-infra-dev/rspress/releases/tag/v2.1.0)

- **Тип**: `boolean | SitemapOptions`
- **По умолчанию**: `true`

Генерирует `sitemap.xml` в выходной директории при продакшен-сборке. Эта функция встроена в Rspress и не требует плагина. Она также работает, когда `ssg` равно `false`. Существующие файлы sitemap, скопированные из директории `public`, сохраняются. Сгенерированные URL следуют настройке `route.cleanUrls`.

Настройте [`siteOrigin`](#siteorigin), чтобы карта сайта содержала абсолютные URL. Rspress объединяет `siteOrigin`, [`base`](#base) и путь маршрута каждой страницы:

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

export default defineConfig({
  siteOrigin: 'https://example.com',
  base: '/docs/',
  // sitemap включён по умолчанию.
});
```

Установите `sitemap: false`, чтобы отключить генерацию, или передайте объект с параметрами для её настройки:

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

export default defineConfig({
  siteOrigin: 'https://example.com',
  sitemap: {
    defaultChangeFreq: 'weekly',
    defaultPriority: '0.7',
  },
});
```

Параметры имеют следующий тип; `SitemapOptions` экспортируется из `@rspress/core`:

```ts
type ChangeFreq =
  'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';

type Priority =
  | '0.0'
  | '0.1'
  | '0.2'
  | '0.3'
  | '0.4'
  | '0.5'
  | '0.6'
  | '0.7'
  | '0.8'
  | '0.9'
  | '1.0';

// https://www.sitemaps.org/protocol.html
interface Sitemap {
  loc: string;
  lastmod?: string;
  changefreq?: ChangeFreq;
  priority?: Priority;
}

interface CustomMaps {
  [routePath: string]: Sitemap;
}

export interface SitemapOptions {
  siteUrl?: string;
  customMaps?: CustomMaps;
  defaultPriority?: Priority;
  defaultChangeFreq?: ChangeFreq;
}
```

### sitemap.siteUrl

- **Тип**: `string`
- **По умолчанию**: [`siteOrigin`](#siteorigin) + [`base`](#base) или `base`, если `siteOrigin` не настроен

Переопределяет URL развёртывания, используемый в записях sitemap. Укажите абсолютный URL, включающий базовый путь, например `https://example.com/docs/`. Это значение имеет приоритет над `siteOrigin` и `base`. Принимаются только URL по протоколу HTTP(S) без строк запроса и фрагментов.

Если не настроены ни `sitemap.siteUrl`, ни `siteOrigin`, записи используют `base + routePath` и остаются относительными путями. Настройте любое из этих значений, чтобы генерировать абсолютные URL в карте сайта.

### sitemap.customMaps

- **Тип**: `Record<string, Sitemap>`
- **По умолчанию**: `{}`

Переопределяет значения sitemap для отдельных страниц. Ключи — пути маршрутов без `base`, а значения переопределяют сгенерированные `loc`, `lastmod`, `changefreq` и `priority`. По умолчанию `lastmod` — это время изменения исходного файла. Эта опция настраивает существующие страницы, но не добавляет маршруты.

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

export default defineConfig({
  siteOrigin: 'https://example.com',
  base: '/docs/',
  sitemap: {
    customMaps: {
      '/guide': {
        loc: 'https://example.com/docs/guide',
        lastmod: '2026-01-01',
        changefreq: 'weekly',
        priority: '0.8',
      },
    },
  },
});
```

### sitemap.defaultChangeFreq

- **Тип**: `ChangeFreq`
- **По умолчанию**: `'monthly'`

Значение `changefreq` по умолчанию для каждой страницы. Доступные значения: `'always'`, `'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'yearly'` и `'never'`. Используйте `customMaps`, чтобы переопределить его для конкретной страницы.

### sitemap.defaultPriority

- **Тип**: `Priority`
- **По умолчанию**: `'0.5'`

Значение `priority` по умолчанию для каждой страницы — от `'0.0'` до `'1.0'` с шагом `0.1`. Для корневого маршрута `/` используется `'1.0'`. Используйте `customMaps`, чтобы переопределить его для конкретной страницы.

## mediumZoom

- **Тип**: `boolean` | `{ selector?: string }`
- **По умолчанию**: `true`

Определяет, включён ли режим увеличения изображений. По умолчанию он включён; установите `mediumZoom` в `false`, чтобы отключить его.

> Увеличение изображений реализовано с помощью библиотеки [medium-zoom](https://github.com/francoischalifour/medium-zoom).

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

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

export default defineConfig({
  // Отключите увеличение изображений
  mediumZoom: false,
  // Настройте CSS-селектор для изображений, которые могут увеличиваться при масштабировании. По умолчанию используется '.rspress-doc img'
  mediumZoom: {
    selector: '.rspress-doc img',
  },
});
```

## search

- **Тип**:

```ts
type SearchOptions = {
  searchHooks?: string;
  versioned?: boolean;
  codeBlocks?: boolean;
};
```

:::tip
Чтобы исключить отдельную страницу из поискового индекса, установите [`search: false`](/rspress-russian/api/config/config-frontmatter.md#search) в её метаданных.
:::

### searchHooks

- **Тип**: `string`
- **По умолчанию**: `undefined`

Используйте `searchHooks` для добавления пользовательской логики во время выполнения поиска. Например:

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

export default defineConfig({
  search: {
    searchHooks: path.join(__dirname, 'searchHooks.ts'),
  },
});
```

Подробную информацию о хуках можно найти в разделе [Настройка поиска](/rspress-russian/guide/advanced/custom-search.md).

### versioned

- **Тип**: `boolean`
- **По умолчанию**: `true`

При использовании [`multiVersion`](/rspress-russian/guide/basic/multi-version.md) по умолчанию для каждой версии создаётся отдельный индекс поиска, благодаря чему результаты поиска содержат только страницы из той версии, которую пользователь просматривает в данный момент. Установите `versioned` в `false`, чтобы отключить это поведение и включить в результаты поиска все версии.

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

export default defineConfig({
  search: {
    versioned: false,
  },
});
```

### codeBlocks

- **Тип**: `boolean`
- **По умолчанию**: `true`

Включать ли содержимое блоков кода в поисковый индекс, чтобы пользователи могли искать по коду внутри блоков.

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

export default defineConfig({
  search: {
    codeBlocks: false,
  },
});
```

## globalUIComponents

- **Тип**: `(string | [string, object])[]`
- **По умолчанию**: `[]`

Через параметр `globalUIComponents` можно зарегистрировать глобальные UI-компоненты, например:

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

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});
```

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

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

export default defineConfig({
  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` на странице для реализации увеличения изображений.
- Отправки данных о просмотрах страниц при изменении маршрута.

## multiVersion

- **Тип**: `{ default: string; versions: string[] }`

Включите поддержку нескольких версий с помощью `multiVersion`. Например:

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

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});
```

Параметр `default` — это версия по умолчанию, а `versions` — список всех доступных версий.

## route

- **Тип**: `Object`

Пользовательская настройка маршрутов.

### route.include

- **Тип**: `string[]`
- **По умолчанию**: `[]`

Добавляет дополнительные файлы в таблицу маршрутов. По умолчанию в неё включаются только файлы из корневого каталога документации. Например:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    include: ['other-dir/**/*.{md,mdx}'],
  },
});
```

> Примечание: строки в массиве поддерживают glob-шаблоны. Glob-выражение должно быть задано относительно корневого каталога документации и включать соответствующие расширения файлов.

:::note Примечание

Для более гибкой настройки маршрутов страниц и сопоставления файлов с содержимым рекомендуется использовать хук [addPages](/rspress-russian/plugin/system/plugin-api.md#addpages) в собственном плагине Rspress.

:::

### route.exclude

- **Тип**: `string[]`
- **По умолчанию**: `[]`

Исключить некоторые файлы из маршрутов. Например:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    exclude: ['custom.tsx', 'component/**/*'],
  },
});
```

> Примечание: строки в массиве поддерживают glob-шаблоны. Glob-выражение должно быть задано относительно корневого каталога документации.

### route.excludeConvention

- **Тип**: `string[]`
- **По умолчанию**: `['**/_[^_]*']`

[Соглашение о маршрутизации](/rspress-russian/guide/use-mdx/components.md), упрощающее хранение компонентов в [каталоге документации](/rspress-russian/api/config/config-basic.md#root). По умолчанию файлы, имена которых начинаются с `_`, исключаются.

Если вам действительно нужны маршруты, начинающиеся с `_`, вы можете изменить это правило, например, задать исключение только для файлов, начинающихся с `_fragment-`:

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

export default defineConfig({
  route: {
    excludeConvention: ['**/_fragment-*'],
  },
});
```

### route.extensions

- **Тип**: `string[]`
- **По умолчанию**: `['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']`

Расширения файлов, которые следует включать в таблицу маршрутов. По умолчанию Rspress включает все файлы с расширениями `'js'`, `'jsx'`, `'ts'`, `'tsx'`, `'md'` и `'mdx'`. Чтобы задать собственный список расширений, используйте эту опцию:

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    extensions: ['.md', '.mdx'],
  },
});
```

### route.cleanUrls

- **Тип**: `Boolean`
- **По умолчанию**: `true` (`false` до v2.1.0)

Генерирует URL-адреса без расширений файлов. Установите `cleanUrls` в `false`, чтобы сохранить суффикс `.html`.

:::warning Требуется поддержка сервера

При включении этой функции может потребоваться дополнительная настройка на вашей хостинг-платформе. Для корректной работы сервер должен отдавать файл `/foo.html` при обращении по адресу `/foo` без редиректа.

:::

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    cleanUrls: false,
  },
});
```

### route.cleanUrlsRedirect

- **Тип**: `Boolean`
- **По умолчанию**: `true`

При включении этой опции Rspress нормализует неканонические URL-адреса в браузере во время запуска клиентского приложения, используя фактически сопоставленный маршрут как единственный источник истины. Итоговый формат URL определяется параметром [`route.cleanUrls`](#routecleanurls).

Параметр `route.cleanUrls` задаёт предпочтительный формат URL, используемый в генерируемых ссылках, тогда как `route.cleanUrlsRedirect` отвечает только за нормализацию адресной строки браузера.

:::warning Клиентская нормализация

Эта опция выполняется после загрузки HTML запрошенной страницы и клиентского приложения. Она использует `history.replaceState` и не возвращает HTTP-перенаправление с кодом 301/308, поэтому не может полностью заменить каноническое перенаправление на стороне сервера или CDN, особенно с точки зрения SEO. Хостинг-платформа всё равно должна отдавать корректную страницу Rspress для запрошенного варианта URL. Если есть возможность, предпочтительно использовать перенаправление на стороне сервера.

:::

#### При `cleanUrls: true`

URL обычных страниц не содержат завершающего слеша, а URL индексных страниц каталогов сохраняют его.

| Входящий URL         | Сопоставленный маршрут | Изменение URL в браузере    |
| -------------------- | ---------------------- | --------------------------- |
| `/file`              | `/file`                | Без изменений               |
| `/file.html`         | `/file`                | `replaceState` → `/file`    |
| `/file/`             | `/file`                | `replaceState` → `/file`    |
| `/file/index`        | `/file`                | `replaceState` → `/file`    |
| `/file/index.html`   | `/file`                | `replaceState` → `/file`    |
| `/folder`            | `/folder/`             | `replaceState` → `/folder/` |
| `/folder.html`       | `/folder/`             | `replaceState` → `/folder/` |
| `/folder/`           | `/folder/`             | Без изменений               |
| `/folder/index`      | `/folder/`             | `replaceState` → `/folder/` |
| `/folder/index.html` | `/folder/`             | `replaceState` → `/folder/` |

#### При `cleanUrls: false`

Для обычных страниц используется суффикс `.html`, а для индексных страниц каталогов — `/index.html`.

| Входящий URL         | Сопоставленный маршрут | Изменение URL в браузере              |
| -------------------- | ---------------------- | ------------------------------------- |
| `/file`              | `/file`                | `replaceState` → `/file.html`         |
| `/file.html`         | `/file`                | Без изменений                         |
| `/file/`             | `/file`                | `replaceState` → `/file.html`         |
| `/file/index`        | `/file`                | `replaceState` → `/file.html`         |
| `/file/index.html`   | `/file`                | `replaceState` → `/file.html`         |
| `/folder`            | `/folder/`             | `replaceState` → `/folder/index.html` |
| `/folder.html`       | `/folder/`             | `replaceState` → `/folder/index.html` |
| `/folder/`           | `/folder/`             | `replaceState` → `/folder/index.html` |
| `/folder/index`      | `/folder/`             | `replaceState` → `/folder/index.html` |
| `/folder/index.html` | `/folder/`             | Без изменений                         |

Например, URL-адреса `/ru/guide/start/introduction.html` и `/ru/guide/start/introduction/index.html` соответствуют маршруту `/ru/guide/start/introduction`; итоговый URL будет приведён к формату, заданному параметром `cleanUrls`, без потери префикса локали.

Форматы канонических URL соответствуют механизму [HTML handling](https://developers.cloudflare.com/workers/static-assets/routing/advanced/html-handling/) в Cloudflare. Однако Cloudflare выполняет HTTP-перенаправления на стороне сервера, тогда как эта опция лишь обновляет URL в адресной строке браузера.

Установите `cleanUrlsRedirect` в `false`, чтобы отключить нормализацию URL в браузере.

```js
import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    cleanUrlsRedirect: false,
  },
});
```

### route.localeRedirect


[Добавлено в v2.0.19](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.19)

- **Тип**: `'auto' | 'never' | 'only-default-lang'`
- **По умолчанию**: `'auto'`

Управляет перенаправлением новых посетителей на ближайшую настроенную локаль на основе `window.navigator.language`:

- `auto`: Перенаправлять с любой локали на ближайшую настроенную локаль.
- `never`: Отключить автоматические перенаправления на локаль.
- `only-default-lang`: Перенаправлять только при открытии посетителем локали по умолчанию.

:::tip Предпочтительны перенаправления на стороне сервера

Этот параметр выполняет перенаправление в браузере. Для рабочих сайтов по возможности рекомендуется обрабатывать определение локали и перенаправления на стороне сервера или на CDN edge. В этом случае посетитель перенаправляется до отправки HTML, и перенаправление не зависит от JavaScript на стороне клиента.

:::

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

export default defineConfig({
  route: {
    localeRedirect: 'never',
  },
});
```

### route.useTransitions


[Добавлено в v2.0.17](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.17)

- **Тип**: `Boolean`
- **По умолчанию**: `true`

Включает параллельную оптимизированную маршрутизацию для внутренних ссылок, отображаемых стандартным компонентом `Link` в Rspress. Это относится к ссылкам в содержимом Markdown и MDX, а также к навигационным ссылкам темы по умолчанию, например элементам боковой панели.

По умолчанию этот параметр включён. Переходы между внутренними страницами оборачиваются в `React.startTransition`, если только вы явно не установите `useTransitions` в `false`. Это позволяет избежать блокировки пользовательского ввода во время ресурсоёмкого рендеринга содержимого новой страницы, сохраняя отзывчивость и интерактивность интерфейса при навигации.

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

export default defineConfig({
  route: {
    useTransitions: false,
  },
});
```

### route.prefetchLink


[Добавлено в v2.0.17](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.17)

- **Тип**: `Boolean`
- **По умолчанию**: `true`

По умолчанию компонент `Link` в Rspress выполняет предварительную загрузку ресурсов, соответствующих целевому маршруту, когда пользователь наводит курсор на внутреннюю ссылку, а также использует аналогичное поведение на устройствах с сенсорным экраном. Это сделано для повышения производительности. Установите этот параметр в `false`, чтобы отключить предварительную загрузку.

:::tip

В режиме разработки предварительная загрузка ссылок спроектирована для совместной работы с [`dev.lazyCompilation`](https://rsbuild.rs/config/dev/lazy-compilation), который по умолчанию включён в Rspress. Ленивая компиляция ускоряет запуск, компилируя страницы только при первом переходе к ним, а предварительная загрузка ссылок начинает компиляцию целевого маршрута уже при наведении курсора, сокращая время ожидания при первом открытии этой страницы.

:::

Пример:

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

export default defineConfig({
  route: {
    prefetchLink: false,
  },
});
```

## ssg

- **Тип**: `boolean | { experimentalWorker?: boolean; experimentalLoose?: boolean; }`
- **По умолчанию**: `true`

Управляет тем, рендерится ли содержимое страниц в HTML во время сборки. По умолчанию Rspress включает SSG.

Установите `ssg: false`, чтобы генерировать HTML-оболочки для рендеринга на стороне клиента.

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

export default defineConfig({
  ssg: false,
});
```

:::tip

И [SSG](/rspress-russian/guide/basic/ssg.md), и [SSG-MD](/rspress-russian/guide/basic/ssg-md.md) требуют, чтобы исходный код компилировался в среде SSR. Код, несовместимый с SSR, приведёт к ошибке сборки. Можно попробовать:

1. Сделать код совместимым с SSR. См. раздел [Распространённые проблемы и их решения](/rspress-russian/guide/basic/ssg.md#common-issues-and-solutions) в руководстве по SSG.

2. Если ваш код не поддерживает SSR, установите и `ssg: false`, и `llms: false`:

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

   export default defineConfig({
     ssg: false,
     llms: false,
   });
   ```

:::

### experimentalWorker

- **Тип**: `boolean`
- **По умолчанию**: `false`

При включении Rspress использует воркеры для ускорения SSG и снижения потребления памяти. Это подходит для крупных сайтов документации и основано на [tinypool](https://github.com/tinylibs/tinypool).

### experimentalExcludeRoutePaths

- **Тип**: `(string | RegExp)[]`
- **По умолчанию**: `[]`

Исключает выбранные страницы из SSG, чтобы они использовали CSR-HTML напрямую. Это может помочь крупным сайтам документации обойти ошибки SSG для небольшого количества страниц, однако не рекомендуется использовать это как поведение по умолчанию.

Эта опция влияет только на SSG и не исключает страницы из SSG-MD. Если исключённые страницы несовместимы с SSR, сделайте их совместимыми с SSR или установите `llms: false`, чтобы отключить SSG-MD.

## replaceRules

- **Тип**: `{ search: string | RegExp; replace: string; }[]`
- **По умолчанию**: `[]`

С помощью `replaceRules` можно задать глобальные правила замены текста для всего сайта. Правила применяются ко всем элементам: к файлам `_meta.json`, к метаданным, к содержимому и заголовкам документов.

```ts title="rspress.config.ts"
export default {
  replaceRules: [
    {
      search: /foo/g,
      replace: 'bar',
    },
  ],
};
```

## languageParity

- **Тип**: `Object`

Сканирует файлы `md` и `mdx` в корне документации, чтобы выявлять отсутствующие языковые версии и обеспечивать согласованность локализаций.

### languageParity.enabled

- **Тип**: `boolean`
- **По умолчанию**: `false`

Включить проверку паритета языков.

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

export default defineConfig({
  languageParity: {
    enabled: true,
  },
});
```

### languageParity.include

- **Тип**: `string[]`
- **По умолчанию**: `[]`

Указывает, какие папки следует проверять. По умолчанию проверяются все файлы в корне документации. Пути должны быть заданы относительно каталога каждого языка. Например:

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

export default defineConfig({
  languageParity: {
    // папки `posts/foods` и `articles` внутри языковых директорий ru/en
    include: ['posts/foods', 'articles'],
  },
});
```

### languageParity.exclude

- **Тип**: `string[]`
- **По умолчанию**: `[]`

Исключает определённые папки и файлы из проверки на паритет языков.

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

export default defineConfig({
  languageParity: {
    exclude: ['excluded-directory', 'articles/secret.md'],
  },
});
```
