Конфигурация темы

Конфигурация темы задаётся в themeConfig. Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    // ...
  },
});

nav

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

Параметр nav — это массив элементов типа NavItem, которые могут иметь следующие формы:

interface NavItem {
  // Текст пункта навигационной панели
  text: string;
  // Ссылка пункта навигации
  link: '/';
  // Является ли ссылкой для скачивания
  download?: boolean;
  // Правило активации (подсветки) пункта навигации
  activeMatch: '^/$|^/';
  // Значок, отображаемый перед текстом в панели навигации
  icon?: string;
  // Метка, отображаемая после текста в панели навигации
  tag?: string;
}

Значение activeMatch сопоставляется с текущим маршрутом. Когда маршрут соответствует правилу activeMatch, пункт навигации подсвечивается. По умолчанию activeMatch использует link элемента навигации.

Для локальных значков поместите изображение в каталог public и укажите его через абсолютный путь, например /icon.png. Также поддерживаются встроенные строки SVG, эмодзи, внешние URL-адреса и data URL.

Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Главная',
        link: '/',
        icon: '/icon.png',
      },
      {
        text: 'Руководство',
        link: '/guide/',
      },
    ],
  },
});

Также можно настроить многоуровневые меню в массиве nav со следующим типом:

interface NavGroup {
  text: string;
  // подменю
  items: NavItem[];
  // Значок, отображаемый перед текстом в панели навигации
  icon?: string;
  // Метка, отображаемая после текста в панели навигации
  tag?: string;
}

Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'Главная',
        link: '/',
      },
      {
        text: 'Руководство',
        items: [
          {
            text: 'Первые шаги',
            link: '/guide/getting-started',
          },
          {
            text: 'Дополнительно',
            link: '/guide/advanced',
          },
          // Также поддерживаются вложенные группы
          {
            text: 'Группа',
            items: [
              {
                text: 'Персональный сайт',
                link: 'http://example.com/',
              },
              {
                text: 'Компания',
                link: 'http://example.com/',
              },
            ],
          },
        ],
      },
    ],
  },
});

Тип: Object

Конфигурация боковой панели сайта. Это объект со следующим типом:

// Ключ — путь SidebarGroup
// Значение — массив элементов SidebarGroup
type Sidebar = Record<string, SidebarGroup[]>;

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // Можно ли сворачивать группу
  collapsible?: boolean;
  // Свёрнута ли группа по умолчанию
  collapsed?: boolean;
  // Значок, отображаемый перед текстом в панели навигации
  icon?: string;
  // Метка, отображаемая после текста в панели навигации
  tag?: string;
}

type SidebarItem = {
  // Текст пункта боковой панели
  text: string;
  // Ссылка пункта боковой панели
  link: string;
  // Значок, отображаемый перед текстом в панели навигации
  icon?: string;
  // Метка, отображаемая после текста в панели навигации
  tag?: string;
};

Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Первые шаги',
          icon: '/icon.png',
          items: [
            {
              text: 'Введение',
              link: '/guide/getting-started/introduction',
              icon: '<svg>...</svg>',
              tag: 'new',
            },
            {
              text: 'Установка',
              link: '/guide/getting-started/installation',
            },
          ],
        },
        {
          text: 'Дополнительно',
          items: [
            {
              text: 'Настройка',
              link: '/guide/advanced/customization',
            },
            {
              text: 'Markdown',
              link: '/guide/advanced/markdown',
            },
          ],
        },
      ],
    },
  },
});

Тип: Object
По умолчанию: {}

Настройка футера главной страницы.

Параметр footer — это объект типа Footer:

export interface Footer {
  message?: string;
}

message — это строка, которая может содержать HTML-контент. Данная строка будет вставлена в футер с помощью dangerouslySetInnerHTML, что позволяет передавать HTML-теги и произвольно оформлять футер.

Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    footer: {
      message:
        '<p>Это футер с <a href="https://example.com">ссылкой</a> и <strong>жирным текстом</strong></p>',
    },
  },
});

lastUpdated

Тип: boolean | { author?: boolean | ((info: { name: string; email: string; filePath: string }) => string) }
По умолчанию: false

Управляет отображением времени последнего обновления на каждой странице документации. Rspress получает это значение из последнего Git-коммита файла.

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    lastUpdated: true,
  },
});

При развёртывании в CI убедитесь, что история Git доступна. Например, в GitHub Actions используйте fetch-depth: 0 для actions/checkout.

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

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    lastUpdated: {
      author: ({ name, email }) => `${name} <${email}>`,
    },
  },
});

socialLinks

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

Добавляет связанные ссылки, например GitHub или X. Связанные ссылки поддерживают пять режимов: link, text, img, dom и github-stars. Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: 'github',
        mode: 'link',
        content: 'https://github.com/sanyuan0704/island.js',
      },
      {
        icon: 'wechat',
        mode: 'text',
        content: 'wechat: foo',
      },
      {
        icon: 'qq',
        mode: 'img',
        content: '/qrcode.png',
      },
      {
        icon: 'github',
        mode: 'dom',
        content:
          '<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/rjhwzy/ljhwZthlaukjlkulzlp/rspress/rspress-navbar-logo-0904.png" alt="logo" id="logo" class="mr-4 rspress-logo dark:hidden">',
      },
      {
        icon: 'github',
        mode: 'github-stars',
        content: 'https://github.com/web-infra-dev/rspress',
      },
    ],
  },
});

В режиме link при клике на иконку открывается ссылка.
В режиме text при наведении на иконку отображается всплывающая подсказка с заданным текстом.
В режиме img при наведении на иконку отображается всплывающая подсказка с изображением. Изображение должно находиться в каталоге public.
В режиме dom передаётся HTML-строка для прямого рендеринга в content. Её нужно заключить в кавычки.
В режиме github-stars значение content должно быть URL-адресом репозитория GitHub. Количество звёзд репозитория запрашивается через GitHub REST API и отображается рядом с иконкой. Результат кэшируется в localStorage на один час, чтобы избежать превышения лимита запросов API. Если запрос не удался (отсутствует интернет, превышен лимит, приватный репозиторий), иконка превращается в обычную ссылку.

Связанные ссылки поддерживают следующие типы иконок, выбираемые через атрибут icon:

export type SocialLinkIcon =
  | 'lark'
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'x'
  | 'youtube'
  | 'wechat'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | 'X'
  | 'bluesky'
  | 'npm'
  | { svg: string };

Чтобы использовать собственную иконку, передайте объект с полем svg. Значение svg — это содержимое пользовательской иконки:

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

export default defineConfig({
  themeConfig: {
    socialLinks: [
      {
        icon: {
          svg: '<svg>foo</svg>',
        },
        mode: 'link',
        content: 'https://github.com/',
      },
    ],
  },
});

nextPageText

Тип: string
По умолчанию: Next Page

Текст ссылки «Следующая страница». Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    nextPageText: 'Следующая страница',
  },
});

locales

Тип: Array<LocaleConfig>
По умолчанию: undefined

Конфигурация i18n. Это массив объектов LocaleConfig:

export interface LocaleConfig {
  /**
   * Общая локальная конфигурация сайта, имеет более высокий приоритет, чем `locales`
   */
  // код языка
  lang?: string;
  // Заголовок HTML-страницы, имеет приоритет над `themeConfig.title`
  title?: string;
  // Описание HTML-страницы, имеет приоритет над `themeConfig.description`
  description?: string;
  // Отображаемый текст для соответствующего языка
  label: string;
}

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

darkMode

Тип: boolean | 'dark' | 'light' | 'auto' | 'force-light' | 'force-dark' | 'force-auto'
По умолчанию: true

Когда включена тёмная тема, Rspress добавляет класс dark к элементу <html>. Для настройки стилей тёмной темы можно использовать селектор html.dark:

html.dark .custom-content {
  color: white;
}

Настраиваем поведение светлой и тёмной тем:

true: то же, что и 'auto'.
false: то же, что и 'force-light'.
'light': отображать кнопку переключения и использовать светлую тему по умолчанию, если пользователь ещё не сохранил свои предпочтения.
'dark': отображать кнопку переключения и использовать тёмную тему по умолчанию, если пользователь ещё не сохранил свои предпочтения.
'auto': отображать кнопку переключения и по умолчанию следовать системным настройкам пользователя, если пользователь ещё не сохранил свои предпочтения.
'force-light': всегда использовать светлую тему и скрыть кнопку переключения.
'force-dark': всегда использовать тёмную тему и скрыть кнопку переключения.
'force-auto': всегда следовать системным настройкам пользователя и скрыть кнопку переключения.

Например, чтобы всегда использовать тёмную тему и скрыть кнопку переключения:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    darkMode: 'force-dark',
  },
});

editLink

Тип:

interface EditLink {
  /**
   * Пользовательский URL репозитория для ссылки «Редактировать страницу».
   */
  docRepoBaseUrl: string;
}

По умолчанию: undefined

Отображает ссылку «Редактировать страницу» на сервисе управления Git (например, GitHub, GitLab). Ссылка отображается как в подвале документа, так и в панели оглавления.

Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    editLink: {
      docRepoBaseUrl:
        'https://github.com/web-infra-dev/rspress/tree/main/website/docs',
    },
  },
});

enableContentAnimation

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

Управляет тем, анимируются ли переходы между страницами. Реализовано с помощью View Transition API. Например:

На данный момент анимация не настраивается.

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    enableContentAnimation: true,
  },
});

enableAppearanceAnimation

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

Управляет тем, анимируется ли переключение между светлой и тёмной темой. Реализовано с помощью View Transition API. Например:

На данный момент анимация не настраивается.

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    enableAppearanceAnimation: true,
  },
});

search

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

Отображать ли поле поиска. Например:

rspress.config.ts

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

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

enableScrollToTop

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

Включает кнопку прокрутки наверх на страницах документации. Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    enableScrollToTop: true,
  },
});

localeRedirect

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

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

Конфигурация перенесена

Этот параметр был перенесён в route.localeRedirect. themeConfig.localeRedirect по-прежнему поддерживается для обратной совместимости, но считается устаревшим. Перенесите параметр в route; если заданы оба параметра, приоритет имеет route.localeRedirect.

rspress.config.ts

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

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

fallbackHeadingTitle

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

Определяет, используется ли title из метаданных как резервный вариант, если в документе отсутствует заголовок H1. Например:

rspress.config.ts

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

export default defineConfig({
  themeConfig: {
    fallbackHeadingTitle: false,
  },
});

---
title: Заголовок документа
---

## Содержимое

llmsUI

Тип:

type LlmsUI =
  | boolean
  | {
      injectLlmsHint?: boolean;
      viewOptions?: false | Array<'markdownLink' | 'chatgpt' | 'claude'>;
      placement?: 'title' | 'outline';
    };

По умолчанию: false (автоматически устанавливается в true, когда настроено llms: true)

Конфигурация UI-компонентов llms. При включении LlmsCopyButton и LlmsViewOptions автоматически добавляются под всеми заголовками H1 по умолчанию или как строки в панели оглавления.

Это полезно при использовании функции llms для генерации файлов llms.txt, поскольку пользователи могут копировать или открывать Markdown-контент в ИИ-инструментах.

Предупреждение

SSG-MD выполняется только на этапе сборки, поэтому копирование Markdown-контента не работает в режиме dev. Сначала выполните rspress build, затем используйте rspress preview для отладки. См. различия между режимами разработки и сборки для подробностей.

Например:

rspress.config.ts

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

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      injectLlmsHint: true,
      viewOptions: ['markdownLink', 'chatgpt', 'claude'],
      placement: 'outline',
    },
  },
});

injectLlmsHint

Добавлено в v2.0.18

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

Этот параметр определяет, будет ли подсказка с директивой для LLM внедряться в сгенерированные страницы. Один и тот же компонент LlmsHint имеет две формы вывода:

В HTML-выводе SSG он отображается как визуально скрытый текстовый DOM-элемент в верхней части страницы. При этом не используются display: none, атрибут hidden, aria-hidden или вложенные ссылки, чтобы преобразование HTML в Markdown на стороне агента могло сохранить директиву в виде текста.
В Markdown-выводе SSG-MD он отображается в виде строки с цитатой в верхней части Markdown-страницы.

Если предположить, что siteOrigin имеет значение https://example.com, следующая HTML-директива будет внедрена в страницу /guide/:

<div class="rp-llms-hint" style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0">For AI agents: the complete documentation index is available at https://example.com/llms.txt, the full documentation bundle is available at https://example.com/llms-full.txt, and this page is available as Markdown at https://example.com/guide/index.md.</div>

Markdown-вывод SSG-MD для той же страницы начинается с:

> For AI agents: the complete documentation index is available at https://example.com/llms.txt, the full documentation bundle is available at https://example.com/llms-full.txt, and this page is available as Markdown at https://example.com/guide/index.md.

URL-адреса автоматически включают настроенные префиксы siteOrigin, base, локали и версии. Если siteOrigin не задан, URL-адреса остаются путями с учётом base.

Установите injectLlmsHint в false, чтобы отключить это поведение:

rspress.config.ts

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

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      injectLlmsHint: false,
    },
  },
});

viewOptions

Тип: false | Array<'markdownLink' | 'chatgpt' | 'claude'>
По умолчанию: ['markdownLink', 'chatgpt', 'claude']

Опции для выпадающего меню LlmsViewOptions. Встроенные варианты включают:

'markdownLink': Копировать ссылку на markdown-файл
'chatgpt': Открыть в ChatGPT
'claude': Открыть в Claude

Установите viewOptions в значение false или [], чтобы скрыть интерфейс параметров представления.

placement

Тип: 'title' | 'outline'
По умолчанию: 'title'

Определяет, где отображаются UI-компоненты LLMS.

'title': Показывать в виде кнопок под заголовком H1 (поведение по умолчанию)
'outline': Показывать в виде отдельных строк в панели оглавления

rspress.config.ts

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

export default defineConfig({
  llms: true,
  themeConfig: {
    llmsUI: {
      placement: 'outline',
    },
  },
});

#Конфигурация темы

#nav

#sidebar

#footer

#lastUpdated

#socialLinks

#nextPageText

#locales

#darkMode

#editLink

#enableContentAnimation

#enableAppearanceAnimation

#search

#enableScrollToTop

#localeRedirect

#fallbackHeadingTitle

#llmsUI

#injectLlmsHint

#viewOptions

#placement

Конфигурация темы

nav

sidebar

footer

lastUpdated

socialLinks

nextPageText

locales

darkMode

editLink

enableContentAnimation

enableAppearanceAnimation

search

enableScrollToTop

localeRedirect

fallbackHeadingTitle

llmsUI

injectLlmsHint

viewOptions

placement