🚧 Rspress 2.0 document is under development
close
Rspress
  • English

      • Build config

      builderConfig

      • Type: RsbuildConfig

      Used to customize the configurations of Rsbuild. For detailed configurations, please refer to Rsbuild - Config.

      rspress.config.ts
      export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});
      • Example: Use tools.rspack to modify the Rspack configuration, such as registering a webpack or Rspack plugin:
      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

      If you want to modify the output directory, please use outDir.

      builderConfig.plugins

      • Type: RsbuildPlugin[]

      To register Rsbuild plugins.

      You can leverage Rsbuild's extensive plugin ecosystem to enhance and extend your build capabilities.

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

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});
      rspress.config.ts
      import { defineConfig } from '@rspress/core';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginGoogleAnalytics({
        // replace this with your Google tag ID
        id: 'G-xxxxxxxxxx',
      }),
    ],
  },
});
      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',
        // ...options
      }),
    ],
  },
});

      You can also override the built-in plugin @rsbuild/plugin-react and customize the plugin options.

      For example:

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

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginReact({
        // ...options
      }),
    ],
  },
});

      Default config

      If you need to view the default Rspack or Rsbuild configs, you can add the DEBUG=rsbuild parameter when running the rspress dev or rspress build command:

      DEBUG=rsbuild rspress dev

      After execution, the rsbuild.config.js file is created in the doc_build directory, which contains the complete builderConfig.

      Please refer to Rsbuild - Debug Mode for more information on how to debug the Rsbuild.

      markdown

      Configure MDX-related compilation abilities.

      markdown.remarkPlugins

      • Type: Array
      • Default: []

      Configure the remark plugins. for example:

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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

      markdown.rehypePlugins

      • Type: Array

      Configure the rehype plugin. for example:

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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

      markdown.shiki

      • Type: import('@shikijs/rehype').RehypeShikiOptions

      • Default:

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

      Configure Shiki-related options. For details, see RehypeShikiOptions.

      • Type:
      export type RemarkLinkOptions = {
  checkDeadLinks?:
    | boolean
    | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};
      • Default: { checkDeadLinks: true, autoPrefix: true }

      Configure link-related options.

      • Type: boolean | { excludes: string[] | ((url: string) => boolean) }
      • Default: true

      After enabling this configuration, Rspress will check the links in the document based on convention routing. If an inaccessible link occurs, the build will throw an error and exit.

      If there is a misjudgment of links, you can ignore the error through the excludes configuration:

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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

      markdown.link.autoPrefix

      • Type: boolean
      • Default: true

      After enabling this config, Rspress will automatically add prefixes to links in documents based on the conventional routing about i18n and Multi version.

      If a user writes a link [](/guide/getting-started) in docs/zh/guide/index.md, Rspress will automatically convert it to [](/zh/guide/getting-started).

      markdown.showLineNumbers

      • Type: boolean

      Whether to display the line number of the code block. Defaults to false.

      markdown.defaultWrapCode

      • Type: boolean

      Whether to enable long code line wrapping display by default. Defaults to false.

      markdown.globalComponents

      • Type: string[]

      Register component to the global scope, which will make it automatically available in every MDX file, without any import statements.For example:

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

      Then you can use the Alert component in any MDX file:

      test.mdx
      <Alert type="info">This is a info alert</Alert>