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。

      全局启用后，可以在代码块 meta 中使用 lineNumbers=false 来为特定代码块禁用行号。反之，全局未启用时，可以使用 lineNumbers 或 lineNumbers=true 来为特定代码块启用行号。详见显示代码行号。

      markdown.defaultWrapCode

      • 类型: boolean

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

      全局启用后，可以在代码块 meta 中使用 wrapCode=false 来为特定代码块禁用换行。反之，全局未启用时，可以使用 wrapCode 或 wrapCode=true 来为特定代码块启用换行。详见代码换行。

      markdown.crossCompilerCache

      • 类型: boolean
      • 默认值: true

      是否在 rspress build 时启用跨编译器缓存。启用后，Rspress 会在多个编译器（web 和 node）之间缓存 MDX 解析结果，从而加速生产环境构建，构建时间可减少约 10%。

      该选项仅在生产环境构建时生效，灵感来自 Docusaurus。

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

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

      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>

      markdown.extractDescription

      • 类型: boolean
      • 默认值: true

      是否自动从 Markdown 内容中提取描述。启用后，Rspress 会提取 h1 标题下方第一段有内容的段落作为页面描述。如果在 frontmatter 中指定了 description，则优先使用，跳过自动提取。

      提取的描述用于 <meta name="description"> 和 Open Graph 的 <meta property="og:description"> 标签。详情请参阅自定义 Head 标签 - description 的获取方式。

      markdown.cjkFriendlyEmphasis

      • 类型: boolean
      • 默认值: true

      是否启用对 CJK（中日韩）友好的强调和删除线解析。启用后，即使标记内部含有标点符号（CJK 或 ASCII），只要标记外侧紧邻 CJK 字符，**、* 和 ~~ 也能正确解析为强调或删除线。

      此选项解决了 CommonMark 规范的一个限制，该限制导致强调标记在 CJK 字符相邻时无法正常工作。例如，未启用此选项时 **该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。 中的第一句不会被渲染为粗体，因为闭合 ** 后紧跟着 CJK 字符。有关此扩展的更多详情，请参见 markdown-cjk-friendly。

      默认启用。如需禁用：

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

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