Базовая конфигурация
root
- Тип:
string - По умолчанию:
docs
Указывает корневой каталог документации. Например:
Эта опция поддерживает как относительные, так и абсолютные пути. Относительные пути разрешаются относительно текущей рабочей директории (cwd).
В качестве аргумента командной строки также можно передать корневой каталог документации:
base
- Тип:
string - По умолчанию:
/
Базовый путь для развёртывания. Например, если вы планируете разместить сайт по адресу https://foo.github.io/bar/, то значение 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/":
title
- Тип:
string - По умолчанию:
"Rspress"
Название сайта. Rspress использует его в качестве заголовка HTML-страницы. Например:
description
- Тип:
string - По умолчанию:
""
Описание сайта. Rspress использует его в качестве описания HTML-страницы. Например:
icon
- Тип:
string | URL - По умолчанию:
""
Иконка сайта. Rspress использует этот путь в качестве иконки HTML-страницы. Например:
Для обычного пути Rspress ищет иконку в каталоге public. Также можно использовать URL CDN, протокол file:// или объект URL, указывающий на локальный абсолютный путь.
lang
- Тип:
string - По умолчанию:
"en"
Язык сайта по умолчанию. Подробности см. в разделе i18n.
locales
- Тип:
Locale[] - По умолчанию:
undefined
Настраивает поддерживаемые языки и информацию о сайте для каждого языка.
Установите верхнеуровневый параметр lang в один из этих кодов языков, чтобы выбрать язык по умолчанию. Rspress опускает языковой префикс в маршрутах языка по умолчанию.
Например:
Полный пример настройки см. в разделе i18n. О языковых параметрах темы, таких как nav и sidebar, см. в разделе themeConfig.locales.
i18nSourcePath
- Тип:
string - По умолчанию:
path.join(cwd, 'i18n.json')
Указывает путь к файлу источника данных i18n. По умолчанию Rspress читает файл 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), на втором — код языка (locale, например ru или en), а значением — перевод текста для соответствующего языка.
Вот пример изменения встроенных i18n-текстов Rspress:
i18nSource также может быть функцией, например:
Вот встроенные строки i18n в Rspress:
logo
- Тип:
string | { dark: string; light: string; width?: number; height?: number } - По умолчанию:
""
Логотип сайта. Rspress использует его в качестве логотипа в левом верхнем углу панели навигации. В объектной форме необязательные width и height задают внутренние размеры (в пикселях) для обоих изображений; используйте размеры исходных изображений, чтобы сохранить их соотношение сторон и уменьшить сдвиги макета. Например:
Rspress ищет логотип в каталоге public. Также можно использовать URL CDN.
Кроме того, можно задать разные логотипы для светлой и тёмной тем:
logoHref
- Тип:
string - По умолчанию:
/${lang}/
Пользовательский ссылка для логотипа. По умолчанию при клике на логотип происходит переход на главную страницу текущего языка. Например:
logoText
- Тип:
string - По умолчанию:
""
Текст логотипа сайта. Rspress отображает его в левом верхнем углу панели навигации. Например:
outDir
- Тип:
string - По умолчанию:
doc_build
Пользовательская директория для вывода собранного сайта. Например:
themeDir
- Тип:
string - По умолчанию:
theme
Указывает директорию пользовательской темы. По умолчанию Rspress использует директорию theme в текущей рабочей директории в качестве директории пользовательской темы. Вы можете использовать themeDir для её настройки. Например:
Эта опция поддерживает как относительные, так и абсолютные пути. Относительные пути разрешаются относительно текущей рабочей директории.
Подробнее о пользовательских темах см. Кастомная тема.
head
- Тип:
string|[string, Record<string, string>]|(route) => string | [string, Record<string, string>] | undefined - Можно дополнять на отдельной странице через метаданные
Добавляет дополнительные элементы в HTML-элемент <head> страницы при продакшен-сборке.
globalStyles
- Тип:
string - По умолчанию:
undefined
Добавляет глобальные стили из указанного файла стилей. Например:
sitemap
- Тип:
boolean | SitemapOptions - По умолчанию:
true
Генерирует sitemap.xml в выходной директории при продакшен-сборке. Эта функция встроена в Rspress и не требует плагина. Она также работает, когда ssg равно false. Существующие файлы sitemap, скопированные из директории public, сохраняются. Сгенерированные URL следуют настройке route.cleanUrls.
Настройте siteOrigin, чтобы карта сайта содержала абсолютные URL. Rspress объединяет siteOrigin, base и путь маршрута каждой страницы:
Установите sitemap: false, чтобы отключить генерацию, или передайте объект с параметрами для её настройки:
Параметры имеют следующий тип; SitemapOptions экспортируется из @rspress/core:
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 — это время изменения исходного файла. Эта опция настраивает существующие страницы, но не добавляет маршруты.
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.
Пример использования:
search
- Тип:
Чтобы исключить отдельную страницу из поискового индекса, установите search: false в её метаданных.
searchHooks
- Тип:
string - По умолчанию:
undefined
Используйте searchHooks для добавления пользовательской логики во время выполнения поиска. Например:
Подробную информацию о хуках можно найти в разделе Настройка поиска.
versioned
- Тип:
boolean - По умолчанию:
true
При использовании multiVersion по умолчанию для каждой версии создаётся отдельный индекс поиска, благодаря чему результаты поиска содержат только страницы из той версии, которую пользователь просматривает в данный момент. Установите versioned в false, чтобы отключить это поведение и включить в результаты поиска все версии.
codeBlocks
- Тип:
boolean - По умолчанию:
true
Включать ли содержимое блоков кода в поисковый индекс, чтобы пользователи могли искать по коду внутри блоков.
globalUIComponents
- Тип:
(string | [string, object])[] - По умолчанию:
[]
Через параметр globalUIComponents можно зарегистрировать глобальные UI-компоненты, например:
Каждый элемент globalUIComponents может быть либо строкой с путём к файлу компонента, либо кортежем. В форме кортежа первый элемент — путь к файлу компонента, второй — пропсы компонента. Например:
При регистрации глобальных компонентов Rspress автоматически рендерит эти React-компоненты в теме без необходимости их ручного импорта.
Глобальные компоненты могут реализовывать различные пользовательские функции, такие как:
Содержимое компонента затем рендерится в теме, например для добавления кнопки BackToTop.
Также глобальный компонент можно использовать для регистрации побочных эффектов:
Побочные эффекты компонента затем выполняются в теме. Например, они полезны для:
- Перенаправления определённых маршрутов страниц.
- Привязки событий клика к тегам
imgна странице для реализации увеличения изображений. - Отправки данных о просмотрах страниц при изменении маршрута.
multiVersion
- Тип:
{ default: string; versions: string[] }
Включите поддержку нескольких версий с помощью multiVersion. Например:
Параметр default — это версия по умолчанию, а versions — список всех доступных версий.
route
- Тип:
Object
Пользовательская настройка маршрутов.
route.include
- Тип:
string[] - По умолчанию:
[]
Добавляет дополнительные файлы в таблицу маршрутов. По умолчанию в неё включаются только файлы из корневого каталога документации. Например:
Примечание: строки в массиве поддерживают glob-шаблоны. Glob-выражение должно быть задано относительно корневого каталога документации и включать соответствующие расширения файлов.
Для более гибкой настройки маршрутов страниц и сопоставления файлов с содержимым рекомендуется использовать хук addPages в собственном плагине Rspress.
route.exclude
- Тип:
string[] - По умолчанию:
[]
Исключить некоторые файлы из маршрутов. Например:
Примечание: строки в массиве поддерживают glob-шаблоны. Glob-выражение должно быть задано относительно корневого каталога документации.
route.excludeConvention
- Тип:
string[] - По умолчанию:
['**/_[^_]*']
Соглашение о маршрутизации, упрощающее хранение компонентов в каталоге документации. По умолчанию файлы, имена которых начинаются с _, исключаются.
Если вам действительно нужны маршруты, начинающиеся с _, вы можете изменить это правило, например, задать исключение только для файлов, начинающихся с _fragment-:
route.extensions
- Тип:
string[] - По умолчанию:
['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']
Расширения файлов, которые следует включать в таблицу маршрутов. По умолчанию Rspress включает все файлы с расширениями 'js', 'jsx', 'ts', 'tsx', 'md' и 'mdx'. Чтобы задать собственный список расширений, используйте эту опцию:
route.cleanUrls
- Тип:
Boolean - По умолчанию:
true(falseдо v2.1.0)
Генерирует URL-адреса без расширений файлов. Установите cleanUrls в false, чтобы сохранить суффикс .html.
При включении этой функции может потребоваться дополнительная настройка на вашей хостинг-платформе. Для корректной работы сервер должен отдавать файл /foo.html при обращении по адресу /foo без редиректа.
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 индексных страниц каталогов сохраняют его.
При cleanUrls: false
Для обычных страниц используется суффикс .html, а для индексных страниц каталогов — /index.html.
Например, 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 в браузере.
route.localeRedirect
- Тип:
'auto' | 'never' | 'only-default-lang' - По умолчанию:
'auto'
Управляет перенаправлением новых посетителей на ближайшую настроенную локаль на основе window.navigator.language:
auto: Перенаправлять с любой локали на ближайшую настроенную локаль.never: Отключить автоматические перенаправления на локаль.only-default-lang: Перенаправлять только при открытии посетителем локали по умолчанию.
Этот параметр выполняет перенаправление в браузере. Для рабочих сайтов по возможности рекомендуется обрабатывать определение локали и перенаправления на стороне сервера или на CDN edge. В этом случае посетитель перенаправляется до отправки HTML, и перенаправление не зависит от JavaScript на стороне клиента.
route.useTransitions
- Тип:
Boolean - По умолчанию:
true
Включает параллельную оптимизированную маршрутизацию для внутренних ссылок, отображаемых стандартным компонентом Link в Rspress. Это относится к ссылкам в содержимом Markdown и MDX, а также к навигационным ссылкам темы по умолчанию, например элементам боковой панели.
По умолчанию этот параметр включён. Переходы между внутренними страницами оборачиваются в React.startTransition, если только вы явно не установите useTransitions в false. Это позволяет избежать блокировки пользовательского ввода во время ресурсоёмкого рендеринга содержимого новой страницы, сохраняя отзывчивость и интерактивность интерфейса при навигации.
route.prefetchLink
- Тип:
Boolean - По умолчанию:
true
По умолчанию компонент Link в Rspress выполняет предварительную загрузку ресурсов, соответствующих целевому маршруту, когда пользователь наводит курсор на внутреннюю ссылку, а также использует аналогичное поведение на устройствах с сенсорным экраном. Это сделано для повышения производительности. Установите этот параметр в false, чтобы отключить предварительную загрузку.
В режиме разработки предварительная загрузка ссылок спроектирована для совместной работы с dev.lazyCompilation, который по умолчанию включён в Rspress. Ленивая компиляция ускоряет запуск, компилируя страницы только при первом переходе к ним, а предварительная загрузка ссылок начинает компиляцию целевого маршрута уже при наведении курсора, сокращая время ожидания при первом открытии этой страницы.
Пример:
ssg
- Тип:
boolean | { experimentalWorker?: boolean; experimentalLoose?: boolean; } - По умолчанию:
true
Управляет тем, рендерится ли содержимое страниц в HTML во время сборки. По умолчанию Rspress включает SSG.
Установите ssg: false, чтобы генерировать HTML-оболочки для рендеринга на стороне клиента.
И SSG, и SSG-MD требуют, чтобы исходный код компилировался в среде SSR. Код, несовместимый с SSR, приведёт к ошибке сборки. Можно попробовать:
-
Сделать код совместимым с SSR. См. раздел Распространённые проблемы и их решения в руководстве по SSG.
-
Если ваш код не поддерживает SSR, установите и
ssg: false, иllms: false:rspress.config.ts
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, к метаданным, к содержимому и заголовкам документов.
languageParity
- Тип:
Object
Сканирует файлы md и mdx в корне документации, чтобы выявлять отсутствующие языковые версии и обеспечивать согласованность локализаций.
languageParity.enabled
- Тип:
boolean - По умолчанию:
false
Включить проверку паритета языков.
languageParity.include
- Тип:
string[] - По умолчанию:
[]
Указывает, какие папки следует проверять. По умолчанию проверяются все файлы в корне документации. Пути должны быть заданы относительно каталога каждого языка. Например:
languageParity.exclude
- Тип:
string[] - По умолчанию:
[]
Исключает определённые папки и файлы из проверки на паритет языков.

