🚧 Rspress 2.0 文档还在开发中
close
Rspress
  • 中文

      • 构建配置

      builderConfig

      • 类型: RsbuildConfig

      用于自定义 Rsbuild 的配置项，完整配置项请查看 Rsbuild - 配置。

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

      如果你想要修改产物输出目录，请使用 outDir。

      builderConfig.plugins

      • 类型: RsbuildPlugin[]

      用于注册 Rsbuild 插件。

      你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。

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

      你也可以覆盖内置的 @rsbuild/plugin-react 并自定义插件的选项。

      比如：

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

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

      默认配置

      如果你需要查看默认的 Rspack 或 Rsbuild 配置，可以在执行 rspress dev 或 rspress build 命令时，添加 DEBUG=rsbuild 参数：

      DEBUG=rsbuild rspress dev

      在执行后，doc_build 目录下会生成 rsbuild.config.js 文件，里面包含了完整的 builderConfig。

      请查看 Rsbuild - 调试模式 来了解更多调试 Rsbuild 的方法。

      markdown

      配置 MDX 相关的编译能力。

      markdown.remarkPlugins

      • 类型: Array
      • 默认值: []

      用于增加一些自定义 remark 插件。比如：

      rspress.config.ts
      import { defineConfig } from '@rspress/core';
import remarkAutolinkHeadings from 'remark-autolink-headings';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        remarkAutolinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});

      markdown.rehypePlugins

      • 类型: Array

      用于增加一些自定义的 rehype 插件。比如：

      rspress.config.ts
      import { defineConfig } from '@rspress/core';
import rehypeAutoLinkHeadings from 'rehype-autolink-headings';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        rehypeAutoLinkHeadings,
        {
          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。

      • 类型:
      export type RemarkLinkOptions = {
  checkDeadLinks?:
    | boolean
    | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};
      • 默认值: { checkDeadLinks: true, autoPrefix: true }

      配置链接相关的配置。

      • 类型: boolean | { excludes: string[] | ((url: string) => boolean) }
      • 默认值: true

      开启这个配置后，会基于约定式路由对文档中的链接进行检查，若出现无法访问的链接，构建会抛出错误并退出。

      如果存在误判链接的情况，可以通过 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

      开启这个配置后，会基于约定式路由对文档中的链接自动增加关于 国际化 和 多版本 前缀。

      比如，用户在 docs/zh/guide/index.md 中写了一个链接 [](/guide/getting-started)，Rspress 会自动将其转换为 [](/zh/guide/getting-started)。

      markdown.showLineNumbers

      • 类型: boolean

      是否显示代码块的行号。默认为 false。

      markdown.defaultWrapCode

      • 类型: boolean

      是否默认启用长代码换行展示。默认为 false。

      markdown.globalComponents

      • 类型: string[]

      注册全局组件，无需 import 语句，就可以在每个 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')],
  },
});

      这样你就可以在 MDX 文件中使用 Alert 组件了：

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