@modern-js/doc-tools-doc/docs/zh/api/config/config-build.mdx

Website for @modern-js/doc-tools

# 构建配置

## builderConfig

- Type: `Object`

用于自定义 Modern.js Builder 的配置项，完整配置项请查看 [Modern.js Builder - API](https://modernjs.dev/builder/api/index.html)。

比如，将产物目录修改为 `doc_dist`：

```ts title="modern.config.ts"
export default defineConfig({
  doc: {
    builderConfig: {
      output: {
        distPath: {
          root: 'doc_dist',
        },
      },
    },
  },
});
```

## builderPlugins

- Type: `BuilderPlugin[]`

用于加入 [Modern.js Builder 的插件](https://modernjs.dev/builder/plugins/introduction.html)，比如：

```ts title="modern.config.ts"
import { docTools, defineConfig } from '@modern-js/doc-tools';
import { builderPluginStylus } from '@modern-js/builder-plugin-stylus';

export default defineConfig({
  doc: {
    builderPlugins: [builderPluginStylus()],
  },
  plugins: [docTools()],
});
```

### 默认配置

如果你需要查看默认的 `builderConfig`，可以在执行 `modern dev` 或 `modern build` 命令时，添加 `DEBUG=builder` 参数：

```bash
DEBUG=builder modern dev
```

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

> 请查看 [Modern.js Builder - 调试模式](https://modernjs.dev/builder/guide/debug/debug-mode.html) 来了解更多调试 Builder 的方法。

## markdown

- Type: `Object`

配置 MDX 相关的编译能力。

### markdown.remarkPlugins

- Type: `Array`
- Default: `[]`

配置 remark 插件。比如：

```ts title="modern.config.ts"
import { docTools, defineConfig } from '@modern-js/doc-tools';

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

### markdown.rehypePlugins

- Type: `Array`

配置 rehype 插件。比如：

```ts title="modern.config.ts"
import { docTools, defineConfig } from '@modern-js/doc-tools';

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

### markdown.checkDeadLinks

- Type: `boolean`
- Default: `false`

是否检查死链。比如：

```ts title="modern.config.ts"
import { docTools, defineConfig } from '@modern-js/doc-tools';

export default defineConfig({
  doc: {
    markdown: {
      checkDeadLinks: true,
    },
  },
  plugins: [docTools()],
});
```

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

### markdown.experimentalMdxRs

- Type: `boolean`

是否使用 MDX 的 Rust 版本编译器，为实验性质功能。比如：

import MdxRs from '../../fragments/mdx-rs';

<MdxRs />

### markdown.showLineNumbers

- Type: `boolean`

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

### markdown.globalComponents

- Type: `string[]`

注册全局组件，无需通过导入声明，就可以在每个 MDX 文件中使用。比如：

```ts title="modern.config.ts"
import { docTools, defineConfig } from '@modern-js/doc-tools';
import path from 'path';

export default defineConfig({
  doc: {
    markdown: {
      globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
    },
  },
  plugins: [docTools()],
});
```

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

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

:::danger 警告
请勿在配置 `globalComponents` 时开启 `experimentalMdxRs`，否则会导致全局组件不生效。
:::