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

# Конфигурация сборки

## builderConfig

- **Тип**: `RsbuildConfig`

Настраивает конфигурацию Rsbuild. Подробности см. в разделе [Rsbuild — Config](https://rsbuild.rs/config/).

- Пример: Использование [resolve.alias](https://rsbuild.rs/config/resolve/alias) для настройки псевдонимов путей:

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});
```

- Пример: Использование [tools.rspack](https://rsbuild.rs/config/tools/rspack) для изменения конфигурации Rspack, например, для регистрации плагина webpack или Rspack:

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    tools: {
      rspack: async config => {
        const { default: ESLintPlugin } = await import('eslint-webpack-plugin');
        config.plugins?.push(new ESLintPlugin());
        return config;
      },
    },
  },
});
```

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

Чтобы изменить выходную директорию, используйте [outDir](/rspress-russian/api/config/config-basic.md#outdir).

:::

## builderConfig.plugins

- **Тип**: `RsbuildPlugin[]`

Для регистрации [плагинов Rsbuild](https://rsbuild.rs/plugins/list/).

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

- Пример: поддержка Vue SFC с помощью [@rsbuild/plugin-vue](https://rsbuild.rs/plugins/list/plugin-vue)

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});
```

- Пример: добавление Google Analytics с помощью [rsbuild-plugin-google-analytics](https://github.com/rstackjs/rsbuild-plugin-google-analytics).

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginGoogleAnalytics({
        // замените это своим Google tag ID
        id: 'G-xxxxxxxxxx',
      }),
    ],
  },
});
```

- Пример: добавление мета-тегов Open Graph с помощью [rsbuild-plugin-open-graph](https://github.com/rstackjs/rsbuild-plugin-open-graph).

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginOpenGraph({
        title: 'My Website',
        type: 'website',
        // ...параметры
      }),
    ],
  },
});
```

Вы также можете переопределить встроенный плагин [@rsbuild/plugin-react](https://rsbuild.rs/plugins/list/plugin-react) и настроить параметры плагина.

Например:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginReact({
        // ...параметры
      }),
    ],
  },
});
```

### Конфигурация по умолчанию

Чтобы просмотреть конфигурацию Rspack или Rsbuild по умолчанию, установите `DEBUG=rsbuild` при запуске `rspress dev` или `rspress build`:

```bash
DEBUG=rsbuild rspress dev
```

После выполнения команды Rspress создаёт файл `rsbuild.config.js` в директории `doc_build`. Этот файл содержит полную конфигурацию `builderConfig`.

> См. [Rsbuild — Debug Mode](https://rsbuild.rs/guide/debug/debug-mode) для получения дополнительной информации об отладке Rsbuild.

## markdown

Настраивает компиляцию MDX.

### markdown.remarkPlugins

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

Настраивает плагины remark. Например:

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

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        require('remark-autolink-headings'),
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.rehypePlugins

- **Тип**: `Array`

Настраивает плагины rehype. Например:

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

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        require('rehype-autolink-headings'),
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.shiki

- **Тип**: `import('@shikijs/rehype').RehypeShikiOptions`

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

```ts
const cssVariablesTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  variableDefaults: {},
  fontStyle: true,
});
const shikiOptions = {
  theme: cssVariablesTheme,
  defaultLanguage: 'txt',
  lazy: true,
  langs: ['tsx', 'ts', 'js'],
  addLanguageClass: true,
};
```

Настройка параметров, связанных с Shiki. Подробнее см. [RehypeShikiOptions](https://github.com/shikijs/shiki/blob/main/packages/rehype/src/types.ts).

### markdown.link

- **Тип**:

```ts
export type RemarkLinkOptions = {
  checkDeadLinks?:
    boolean | { excludes: string[] | ((url: string) => boolean) };
  checkAnchors?: boolean | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};
```

- **По умолчанию**: `{ checkDeadLinks: true, checkAnchors: true, autoPrefix: true }`

Настройка параметров, связанных со ссылками.

#### markdown.link.checkDeadLinks

- **Тип**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **По умолчанию**: `true`

При включении Rspress проверяет ссылки в документации на соответствие стандартным маршрутам. Если ссылка недоступна, сборка завершается с ошибкой.

Если ссылка помечена как некорректная ошибочно, её можно исключить с помощью `excludes`:

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

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: {
        excludes: ['/guide/getting-started', '/llms.txt'],
      },
    },
  },
});
```

#### markdown.link.checkAnchors

- **Тип:** `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **По умолчанию:** `true` (в версиях до v2.1.0 — `false`)

После включения этой опции Rspress будет проверять, существуют ли якоря внутренних ссылок на целевой странице Markdown или MDX. Проверяются якоря на текущей странице, относительные и абсолютные ссылки, но якоря внешних URL пропускаются.

Установите эту опцию в `false`, чтобы отключить проверку якорей.

Если якорь ошибочно помечен как некорректный, его можно исключить с помощью `excludes`:

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

export default defineConfig({
  markdown: {
    link: {
      checkAnchors: {
        excludes: ['/guide/getting-started#custom-anchor'],
      },
    },
  },
});
```

#### markdown.link.autoPrefix

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

При включении Rspress автоматически добавляет префиксы к ссылкам на основе стандартных маршрутов для [i18n](/rspress-russian/guide/basic/i18n.md) и [мультиверсионности](/rspress-russian/guide/basic/multi-version.md).

Если пользователь напишет ссылку `[](/guide/getting-started)` в `docs/ru/guide/index.md`, Rspress автоматически преобразует её в `[](/ru/guide/getting-started)`.

### markdown.image

- **Тип**:

```ts
export type RemarkImageOptions = {
  checkDeadImages?:
    boolean | { excludes: string[] | ((url: string) => boolean) };
};
```

- **По умолчанию**: `{ checkDeadImages: true }`

Настройка параметров, связанных с изображениями.

#### markdown.image.checkDeadImages

- **Тип**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **По умолчанию**: `true`

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

Для относительных путей к изображениям (например, `./image.png`) файл разрешается относительно текущего документа. Для абсолютных путей к изображениям (например, `/image.png`) файл разрешается из каталога `public`.

Если изображение ошибочно помечено как некорректное, его можно исключить с помощью `excludes`:

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

export default defineConfig({
  markdown: {
    image: {
      checkDeadImages: {
        excludes: ['/generated-diagram.png'],
      },
    },
  },
});
```

### markdown.showLineNumbers

- **Тип**: `boolean`

Управляет отображением номеров строк в блоках кода. По умолчанию — `false`.

При глобальном включении вы можете использовать `lineNumbers=false` в метаданных блока кода, чтобы отключить нумерацию строк для конкретного блока. Напротив, при глобальном отключении вы можете использовать `lineNumbers` или `lineNumbers=true`, чтобы включить нумерацию строк для конкретного блока. Подробности см. в разделе [Нумерация строк](/rspress-russian/guide/use-mdx/code-blocks.md#show-code-line-numbers).

### markdown.defaultWrapCode

- **Тип**: `boolean`

Управляет тем, будут ли длинные строки кода переноситься по умолчанию. По умолчанию — `false`.

При глобальном включении вы можете использовать `wrapCode=false` в метаданных блока кода, чтобы отключить перенос строк для конкретного блока. Напротив, при глобальном отключении вы можете использовать `wrapCode` или `wrapCode=true`, чтобы включить перенос строк для конкретного блока. Подробности см. в разделе [Перенос длинных строк](/rspress-russian/guide/use-mdx/code-blocks.md#wrap-code).

### markdown.defaultCodeOverflow

- **Тип**: `{ height?: number; behavior?: 'fold' | 'scroll' }`

По умолчанию блоки кода в Rspress полностью развёрнуты без поведения переполнения. Вы можете использовать мета-атрибуты, такие как ` ```tsx fold `, для управления переполнением отдельных блоков кода. Эта конфигурация задаёт глобальное поведение переполнения по умолчанию, которое автоматически применяется, когда блоки кода превышают указанную высоту.

- `height`: порог высоты в пикселях. Если не установлен, поведение переполнения не применяется.
- `behavior`: как обрабатывать блоки кода, превышающие высоту. По умолчанию `'scroll'`.
  - `'scroll'`: фиксированная высота с вертикальной полосой прокрутки.
  - `'fold'`: сворачиваемый блок с кнопкой разворачивания/сворачивания.

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

export default defineConfig({
  markdown: {
    defaultCodeOverflow: {
      height: 400,
      behavior: 'fold',
    },
  },
});
```

Отдельные блоки кода могут переопределить значение по умолчанию, используя мета-атрибуты `height` или `fold`. Подробнее см. [Высота блока кода](/rspress-russian/guide/use-mdx/code-blocks.md#code-block-height).

### markdown.crossCompilerCache

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

Включать ли кэш кросс-компилятора для компиляции MDX при выполнении команды `rspress build`. При включении этой опции Rspress будет кэшировать результаты парсинга MDX между разными компиляторами (web и node), что позволяет ускорить процесс продакшен-сборки примерно на 10%.

Опция работает только в продакшен-сборках и вдохновлена соответствующей возможностью в [Docusaurus](https://docusaurus.io/).

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

export default defineConfig({
  markdown: {
    crossCompilerCache: true,
  },
});
```

### markdown.globalComponents

- **Тип**: `string[]`

Регистрирует компоненты глобально, чтобы они были доступны в каждом MDX-файле без необходимости импортировать их вручную. Например:

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

export default defineConfig({
  markdown: {
    globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
  },
});
```

Затем вы можете использовать компонент `Alert` в любом MDX-файле:

```mdx title="test.mdx"
<Alert type="info">Это информационное уведомление</Alert>
```

### markdown.extractDescription

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

Следует ли автоматически извлекать описание из содержимого Markdown. При включении Rspress извлекает первый содержательный абзац под заголовком `h1` в качестве описания страницы. Если `description` указано в [метаданных](/rspress-russian/api/config/config-frontmatter.md#description), оно имеет приоритет, и автоматическое извлечение пропускается.

Извлеченное описание используется для тегов `<meta name="description">` и Open Graph `<meta property="og:description">`. Подробнее см. [Настройка тегов head - Как определяется описание](/rspress-russian/guide/advanced/custom-head.md#how-description-is-determined).

### markdown.cjkFriendlyEmphasis

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

Включает ли парсинг акцента и зачёркивания, дружественный к иероглифам. При включении `**`, `*` и `~~` будут корректно распознаваться как акцент/зачёркивание, когда иероглифы находятся снаружи от маркеров, даже если внутри маркеров присутствует пунктуация.

Это решает [ограничение спецификации CommonMark](https://github.com/commonmark/commonmark-spec/issues/650), при котором маркеры акцента не распознаются корректно, когда рядом находятся иероглифы. Например, `**该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。` без этой опции не отобразит первое предложение жирным, потому что иероглифы следуют сразу за закрывающим `**`. Подробнее об этом расширении см. [markdown-cjk-friendly](https://github.com/tats-u/markdown-cjk-friendly).

Включено по умолчанию. Чтобы отключить:

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

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