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

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

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

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

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

## nav

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

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

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

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

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

Например:

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

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

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

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

Например:

```ts title="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/',
              },
            ],
          },
        ],
      },
    ],
  },
});
```

## sidebar

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

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

```ts
// Ключ — путь 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;
};
```

Например:

```ts title="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',
            },
          ],
        },
      ],
    },
  },
});
```

## footer

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

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

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

```ts
export interface Footer {
  message?: string;
}
```

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

Например:

```ts title="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-коммита файла.

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

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

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

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

```ts title="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`. Например:

```ts title="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`:

```ts
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` — это содержимое пользовательской иконки:

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

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

## locales

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

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

```ts
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`:

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

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

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

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

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

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

## editLink

- **Тип**:

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

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

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

Например:

```ts title="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](https://developer.mozilla.org/docs/Web/API/View_Transitions_API). Например:

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

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

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

## enableAppearanceAnimation

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

Управляет тем, анимируется ли переключение между светлой и тёмной темой. Реализовано с помощью [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transitions_API). Например:

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

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

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

## search

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

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

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

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

## enableScrollToTop

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

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

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

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

## ~~localeRedirect~~

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

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

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

Этот параметр был перенесён в [`route.localeRedirect`](/rspress-russian/api/config/config-basic.md#routelocaleredirect). `themeConfig.localeRedirect` по-прежнему поддерживается для обратной совместимости, но считается устаревшим. Перенесите параметр в `route`; если заданы оба параметра, приоритет имеет `route.localeRedirect`.

:::

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

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

## fallbackHeadingTitle

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

Определяет, используется ли [`title` из метаданных](/rspress-russian/api/config/config-frontmatter.md#title) как резервный вариант, если в документе отсутствует заголовок H1. Например:

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

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

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

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

## llmsUI

- **Тип**:

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

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

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

Это полезно при использовании функции [llms](/rspress-russian/guide/basic/ssg-md.md) для генерации файлов llms.txt, поскольку пользователи могут копировать или открывать Markdown-контент в ИИ-инструментах.

:::warning
SSG-MD выполняется только на этапе сборки, поэтому копирование Markdown-контента не работает в режиме `dev`. Сначала выполните `rspress build`, затем используйте `rspress preview` для отладки. См. [различия между режимами разработки и сборки](/rspress-russian/guide/basic/ssg.md#differences-between-dev-and-build) для подробностей.
:::

Например:

```ts title="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](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.18)

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

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

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

Если предположить, что [`siteOrigin`](/rspress-russian/api/config/config-basic.md#siteorigin) имеет значение `https://example.com`, следующая HTML-директива будет внедрена в страницу `/guide/`:


```html
<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 для той же страницы начинается с:

```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`](/rspress-russian/api/config/config-basic.md#base), локали и версии. Если `siteOrigin` не задан, URL-адреса остаются путями с учётом `base`.

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

```ts title="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'`: Показывать в виде отдельных строк в панели оглавления

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

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