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

builderConfig

Тип: RsbuildConfig

Используется для настройки конфигураций Rsbuild. Подробные конфигурации смотрите в Rsbuild - Config.

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

rspress.config.ts

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

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

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;
      },
    },
  },
});

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

Если вы хотите изменить директорию вывода, используйте параметр outDir.

builderConfig.plugins

Тип: RsbuildPlugin[]

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

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

Пример: Поддержка Vue SFC через @rsbuild/plugin-vue

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.

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.

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

Например:

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:

DEBUG=rsbuild rspress dev

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

Подробнее о том, как отлаживать Rsbuild, смотрите в Rsbuild - Debug Mode.

markdown

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

markdown.remarkPlugins

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

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

rspress.config.ts

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

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

markdown.rehypePlugins

Тип: Array

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

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

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) };
  autoPrefix?: boolean;
};

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

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

markdown.link.checkDeadLinks

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

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

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

rspress.config.ts

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

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

markdown.link.autoPrefix

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

После включения этой конфигурации Rspress будет автоматически добавлять префиксы к ссылкам в документах на основе соглашения о маршрутах для Интернационализации и Мультиверсионности.

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

markdown.image

Type:

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:

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, чтобы включить нумерацию строк для конкретного блока. Подробности см. в разделе Нумерация строк.

markdown.defaultWrapCode

Тип: boolean

Включает перенос длинных строк кода по умолчанию. По умолчанию false.

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

markdown.defaultCodeOverflow

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

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

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

rspress.config.ts

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.

rspress.config.ts

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

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

markdown.globalComponents

Тип: string[]

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

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-файле:

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

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

rspress.config.ts

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

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

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

#builderConfig

#builderConfig.plugins

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

#markdown

#markdown.remarkPlugins

#markdown.rehypePlugins

#markdown.shiki

#markdown.link

#markdown.link.checkDeadLinks

#markdown.link.autoPrefix

#markdown.image

#markdown.image.checkDeadImages

#markdown.showLineNumbers

#markdown.defaultWrapCode

#markdown.defaultCodeOverflow

#markdown.crossCompilerCache

#markdown.globalComponents

#markdown.extractDescription

#markdown.cjkFriendlyEmphasis

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

builderConfig

builderConfig.plugins

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

markdown

markdown.remarkPlugins

markdown.rehypePlugins

markdown.shiki

markdown.link

markdown.link.checkDeadLinks

markdown.link.autoPrefix

markdown.image

markdown.image.checkDeadImages

markdown.showLineNumbers

markdown.defaultWrapCode

markdown.defaultCodeOverflow

markdown.crossCompilerCache

markdown.globalComponents

markdown.extractDescription

markdown.cjkFriendlyEmphasis