Skip to content

Commit

Permalink
docs: improve extend build guide
Browse files Browse the repository at this point in the history
  • Loading branch information
chenjiahan committed Apr 1, 2024
1 parent 6db7cef commit 2259c64
Show file tree
Hide file tree
Showing 4 changed files with 124 additions and 28 deletions.
49 changes: 43 additions & 6 deletions packages/document/docs/en/api/config/config-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## builderConfig

- Type: `Object`
- Type: `RsbuildConfig`

Used to customize the configurations of Rsbuild. For complete configurations, please refer to [Rsbuild - Config](https://rsbuild.dev/config/).
Used to customize the configurations of Rsbuild. For detailed configurations, please refer to [Rsbuild - Config](https://rsbuild.dev/config/).

For example, change the output directory to `doc_dist`:

Expand All @@ -24,20 +24,57 @@ export default defineConfig({

- Type: `RsbuildPlugin[]`

Used to customize the [plugins of Rsbuild](https://rsbuild.dev). For example:
Used to register [Rsbuild plugins](https://rsbuild.dev/plugins/list/).

You can use the rich plugins of Rsbuild in the Rspress project to quickly extend the building capabilities.

- Example: Support Vue SFC through [@rsbuild/plugin-vue](https://rsbuild.dev/plugins/list/plugin-vue)

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
builderPlugins: [pluginVue()],
});
```

- Example: Add Google analytics through [rsbuild-plugin-google-analytics](https://github.com/rspack-contrib/rsbuild-plugin-google-analytics)

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
builderPlugins: [
pluginGoogleAnalytics({
// replace this with your Google tag ID
id: 'G-xxxxxxxxxx',
}),
],
});
```

- Example: Add Open Graph meta tags through [rsbuild-plugin-open-graph](https://github.com/rspack-contrib/rsbuild-plugin-open-graph)

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginStylus } from '@rsbuild/plugin-stylus';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
builderPlugins: [pluginStylus()],
builderPlugins: [
pluginOpenGraph({
title: 'My Website',
type: 'website',
// ...options
}),
],
});
```

### Default Config

If you need to see the default `builderConfig`, you can add the `DEBUG=rsbuild` parameter when running the `rspress dev` or `rspress build` command:
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:

```bash
DEBUG=rsbuild rspress dev
Expand Down
29 changes: 20 additions & 9 deletions packages/document/docs/en/guide/advanced/extend-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@

Rspress builds documents based on [Rsbuild](https://github.com/web-infra-dev/rsbuild).

Rsbuild provides flexible build configurations, you can use [builderConfig](/api/config/config-build.html#builderconfig) to customize these configurations. For example, change the output directory to `doc_dist`:
### Configure Rsbuild

Rsbuild provides a rich set of build configurations. You can customize these configurations through [builderConfig](/api/config/config-build.html#builderconfig). For example, change the output directory to `doc_dist`:

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
Expand All @@ -16,22 +18,31 @@ export default defineConfig({
root: 'doc_dist',
},
},
tools: {
rspack(options) {
// change rspack's options
},
},
},
});
```

:::tip
You can learn more about the configuration options through [Rsbuild - Config](https://rsbuild.dev/config/) documentation.
:::

You can learn more configurations through the [Rsbuild - Config](https://rsbuild.dev/config/) documentation.
### Configure Rspack

Note that Rspress only supports Rspack bundler, so some configurations related to webpack will not work, such as `tools.webpack`. Of course, you can use the `tools.rspack` to customize the Rspack config.
You can configure Rspack through the [tools.rspack](https://rsbuild.dev/config/tools/rspack) option provided by Rsbuild:

:::
```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';

export default defineConfig({
builderConfig: {
tools: {
rspack(options) {
// modify the rspack configuration
},
},
},
});
```

## MDX Compilation

Expand Down
47 changes: 42 additions & 5 deletions packages/document/docs/zh/api/config/config-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## builderConfig

- Type: `Object`
- Type: `RsbuildConfig`

用于自定义 Rsbuild 的配置项,完整配置项请查看 [Rsbuild - 配置](https://rsbuild.dev/zh/config/)

Expand All @@ -24,20 +24,57 @@ export default defineConfig({

- Type: `RsbuildPlugin[]`

用于加入 [Rsbuild 的插件](https://rsbuild.dev/zh/plugins/list/),比如:
用于注册 [Rsbuild 插件](https://rsbuild.dev/zh/plugins/list/)

你可以在 Rspress 项目中使用 Rsbuild 丰富的插件,来快速扩展构建能力。

- 示例:通过 [@rsbuild/plugin-vue](https://rsbuild.dev/plugins/list/plugin-vue) 支持 Vue SFC

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
builderPlugins: [pluginVue()],
});
```

- 示例:通过 [rsbuild-plugin-google-analytics](https://github.com/rspack-contrib/rsbuild-plugin-google-analytics) 添加 Google analytics

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
builderPlugins: [
pluginGoogleAnalytics({
// replace this with your Google tag ID
id: 'G-xxxxxxxxxx',
}),
],
});
```

- 示例:通过 [rsbuild-plugin-open-graph](https://github.com/rspack-contrib/rsbuild-plugin-open-graph) 添加 Open Graph meta 标签

```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';
import { pluginStylus } from '@rsbuild/plugin-stylus';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
builderPlugins: [pluginStylus()],
builderPlugins: [
pluginOpenGraph({
title: 'My Website',
type: 'website',
// ...options
}),
],
});
```

### 默认配置

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

```bash
DEBUG=rsbuild rspress dev
Expand Down
27 changes: 19 additions & 8 deletions packages/document/docs/zh/guide/advanced/extend-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

Rspress 底层基于 [Rsbuild](https://github.com/web-infra-dev/rsbuild) 来进行文档构建。

### Rsbuild 配置

Rsbuild 提供了丰富的构建配置,你可以使用 [builderConfig](/api/config/config-build.html#builderconfig) 来自定义这些配置项。比如,将产物目录修改为 `doc_dist`

```ts title="rspress.config.ts"
Expand All @@ -16,22 +18,31 @@ export default defineConfig({
root: 'doc_dist',
},
},
tools: {
rspack(options) {
// 修改 rspack 的配置
},
},
},
});
```

:::tip
你可以通过 [Rsbuild - 配置](https://rsbuild.dev/zh/config/) 文档来了解更多的配置项。
:::

你可以通过 [Rsbuild - 配置](https://rsbuild.dev/zh/config/) 的文档来了解更多的配置项。
### Rspack 配置

注意,Rspress 仅支持 Rspack 打包工具,因此一些与 webpack 相关的配置项将无法生效,比如 `tools.webpack`。当然,你可以通过 `tools.rspack` 来修改 Rspack 的配置
你可以通过 Rsbuild 提供的 [tools.rspack](https://rsbuild.dev/config/tools/rspack) 选项来修改 Rspack 的配置

:::
```ts title="rspress.config.ts"
import { defineConfig } from 'rspress/config';

export default defineConfig({
builderConfig: {
tools: {
rspack(options) {
// 修改 rspack 的配置
},
},
},
});
```

## MDX 编译插件

Expand Down

0 comments on commit 2259c64

Please sign in to comment.