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

#builderConfig

• Тип: RsbuildConfig

Настраивает конфигурацию Rsbuild. Подробности см. в разделе Rsbuild — Config.

• Пример: Использование resolve.alias для настройки псевдонимов путей:

export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});

• Пример: Использование tools.rspack для изменения конфигурации Rspack, например, для регистрации плагина webpack или Rspack:

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

#builderConfig.plugins

• Тип: RsbuildPlugin[]

Для регистрации плагинов Rsbuild.

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

• Пример: поддержка Vue SFC с помощью @rsbuild/plugin-vue

import { defineConfig } from '@rspress/core';
import { pluginVue } from '@rsbuild/plugin-vue';

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

• Пример: добавление Google Analytics с помощью rsbuild-plugin-google-analytics.

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.

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 и настроить параметры плагина.

Например:

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:

DEBUG=rsbuild rspress dev

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

См. Rsbuild — Debug Mode для получения дополнительной информации об отладке Rsbuild.

#markdown

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

#markdown.remarkPlugins

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

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

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

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

#markdown.rehypePlugins

• Тип: Array

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

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

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

#markdown.shiki

• Тип: import('@shikijs/rehype').RehypeShikiOptions

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

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.

#markdown.link

• Тип:

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

• По умолчанию: { checkDeadLinks: true, checkAnchors: false, autoPrefix: true }

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

#markdown.link.checkDeadLinks

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

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

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

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) }
• По умолчанию: false

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

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

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

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

#markdown.link.autoPrefix

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

При включении Rspress автоматически добавляет префиксы к ссылкам на основе стандартных маршрутов для i18n и мультиверсионности.

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

#markdown.image

• Тип:

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:

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

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

#markdown.showLineNumbers

• Тип: boolean

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

При глобальном включении вы можете использовать lineNumbers=false в метаданных блока кода, чтобы отключить нумерацию строк для конкретного блока. Напротив, при глобальном отключении вы можете использовать lineNumbers или lineNumbers=true, чтобы включить нумерацию строк для конкретного блока. Подробности см. в разделе Нумерация строк.

#markdown.defaultWrapCode

• Тип: boolean

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

При глобальном включении вы можете использовать wrapCode=false в метаданных блока кода, чтобы отключить перенос строк для конкретного блока. Напротив, при глобальном отключении вы можете использовать wrapCode или wrapCode=true, чтобы включить перенос строк для конкретного блока. Подробности см. в разделе Перенос длинных строк.

#markdown.defaultCodeOverflow

• Тип: { height?: number; behavior?: 'fold' | 'scroll' }

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

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

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

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

Отдельные блоки кода могут переопределить значение по умолчанию, используя мета-атрибуты height или fold. Подробнее см. Высота блока кода.

#markdown.crossCompilerCache

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

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

Опция работает только в продакшен-сборках и вдохновлена соответствующей возможностью в Docusaurus.

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

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

#markdown.globalComponents

• Тип: string[]

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

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

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

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

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

#markdown.extractDescription

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

Следует ли автоматически извлекать описание из содержимого Markdown. При включении Rspress извлекает первый содержательный абзац под заголовком h1 в качестве описания страницы. Если description указано в метаданных, оно имеет приоритет, и автоматическое извлечение пропускается.

Извлеченное описание используется для тегов <meta name="description"> и Open Graph <meta property="og:description">. Подробнее см. Настройка тегов head - Как определяется описание.

#markdown.cjkFriendlyEmphasis

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

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

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

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

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

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