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, and this page is available as Markdown at /rspress-russian/api/config/config-basic.md.
close

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

root

  • Тип: string
  • По умолчанию: docs

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

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

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

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

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

rspress dev docs
rspress build docs

base

  • Тип: string
  • По умолчанию: /

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

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

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

siteOrigin

  • Тип: string
  • По умолчанию: ""

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

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

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

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

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

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

title

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

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

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

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

description

  • Тип: string
  • По умолчанию: ""

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

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

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

icon

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

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

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.config.ts
import { defineConfig } from '@rspress/core';

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

locales

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

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

export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}
ПолеОписание
langКод языка. Должен совпадать с именем соответствующей директории в корне документации.
labelОтображаемый текст в переключателе языков панели навигации.
titleЗаголовок сайта для этого языка.
descriptionОписание сайта для этого языка.

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

Например:

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. О языковых параметрах темы, таких как nav и sidebar, см. в разделе themeConfig.locales.

i18nSourcePath

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

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

rspress.config.ts
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  i18nSourcePath: path.join(__dirname, 'config/i18n.json'),
});
Совет

Это имеет тот же эффект, что и размещение файла 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.

Совет

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

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

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

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

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

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

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

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:

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

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

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

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

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

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

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

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}/

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

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

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

logoText

  • Тип: string
  • По умолчанию: ""

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

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

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

outDir

  • Тип: string
  • По умолчанию: doc_build

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

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

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

themeDir

  • Тип: string
  • По умолчанию: theme

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

rspress.config.ts
import { defineConfig } from '@rspress/core';
import path from 'path';

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

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

Подробнее о пользовательских темах см. Кастомная тема.

  • Тип: string | [string, Record<string, string>] | (route) => string | [string, Record<string, string>] | undefined
  • Можно дополнять на отдельной странице через метаданные

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

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

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

rspress.config.ts
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/global.css'),
});
styles/global.css
:root {
  --rp-c-brand: #f00;
}

sitemap

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

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

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

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

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

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

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

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

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

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 + 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 — это время изменения исходного файла. Эта опция настраивает существующие страницы, но не добавляет маршруты.

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.

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

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

export default defineConfig({
  // Отключите увеличение изображений
  mediumZoom: false,
  // Настройте CSS-селектор для изображений, которые могут увеличиваться при масштабировании. По умолчанию используется '.rspress-doc img'
  mediumZoom: {
    selector: '.rspress-doc img',
  },
});
  • Тип:
type SearchOptions = {
  searchHooks?: string;
  versioned?: boolean;
  codeBlocks?: boolean;
};
Совет

Чтобы исключить отдельную страницу из поискового индекса, установите search: false в её метаданных.

searchHooks

  • Тип: string
  • По умолчанию: undefined

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

rspress.config.ts
import { defineConfig } from '@rspress/core';
import path from 'path';

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

Подробную информацию о хуках можно найти в разделе Настройка поиска.

versioned

  • Тип: boolean
  • По умолчанию: true

При использовании multiVersion по умолчанию для каждой версии создаётся отдельный индекс поиска, благодаря чему результаты поиска содержат только страницы из той версии, которую пользователь просматривает в данный момент. Установите versioned в false, чтобы отключить это поведение и включить в результаты поиска все версии.

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

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

codeBlocks

  • Тип: boolean
  • По умолчанию: true

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

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

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

globalUIComponents

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

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

rspress.config.ts
import { defineConfig } from '@rspress/core';
import path from 'path';

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

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

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

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

multiVersion

  • Тип: { default: string; versions: string[] }

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

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

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

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

route

  • Тип: Object

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

route.include

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

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

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

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

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

Примечание

Для более гибкой настройки маршрутов страниц и сопоставления файлов с содержимым рекомендуется использовать хук addPages в собственном плагине Rspress.

route.exclude

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

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

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

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

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

route.excludeConvention

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

Соглашение о маршрутизации, упрощающее хранение компонентов в каталоге документации. По умолчанию файлы, имена которых начинаются с _, исключаются.

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

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'. Чтобы задать собственный список расширений, используйте эту опцию:

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

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

route.cleanUrls

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

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

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

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

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

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

route.cleanUrlsRedirect

  • Тип: Boolean
  • По умолчанию: true

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

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

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

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

При cleanUrls: true

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

Входящий URLСопоставленный маршрутИзменение URL в браузере
/file/fileБез изменений
/file.html/filereplaceState → /file
/file//filereplaceState → /file
/file/index/filereplaceState → /file
/file/index.html/filereplaceState → /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/filereplaceState → /file.html
/file.html/fileБез изменений
/file//filereplaceState → /file.html
/file/index/filereplaceState → /file.html
/file/index.html/filereplaceState → /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 в Cloudflare. Однако Cloudflare выполняет HTTP-перенаправления на стороне сервера, тогда как эта опция лишь обновляет URL в адресной строке браузера.

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

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

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

route.localeRedirect

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

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

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

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

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

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

route.useTransitions

  • Тип: Boolean
  • По умолчанию: true

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

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

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

export default defineConfig({
  route: {
    useTransitions: false,
  },
});
  • Тип: Boolean
  • По умолчанию: true

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

Совет

В режиме разработки предварительная загрузка ссылок спроектирована для совместной работы с dev.lazyCompilation, который по умолчанию включён в Rspress. Ленивая компиляция ускоряет запуск, компилируя страницы только при первом переходе к ним, а предварительная загрузка ссылок начинает компиляцию целевого маршрута уже при наведении курсора, сокращая время ожидания при первом открытии этой страницы.

Пример:

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-оболочки для рендеринга на стороне клиента.

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

export default defineConfig({
  ssg: false,
});
Совет

И SSG, и SSG-MD требуют, чтобы исходный код компилировался в среде SSR. Код, несовместимый с SSR, приведёт к ошибке сборки. Можно попробовать:

  1. Сделать код совместимым с SSR. См. раздел Распространённые проблемы и их решения в руководстве по SSG.

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

    rspress.config.ts
    import { defineConfig } from '@rspress/core';
    
    export default defineConfig({
      ssg: false,
      llms: false,
    });

experimentalWorker

  • Тип: boolean
  • По умолчанию: false

При включении Rspress использует воркеры для ускорения SSG и снижения потребления памяти. Это подходит для крупных сайтов документации и основано на 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, к метаданным, к содержимому и заголовкам документов.

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

languageParity

  • Тип: Object

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

languageParity.enabled

  • Тип: boolean
  • По умолчанию: false

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

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

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

languageParity.include

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

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

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

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

languageParity.exclude

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

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

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

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