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

Website for @modern-js/doc-tools

# 基础配置

## base

- Type: `string`
- Default: `/`

部署基准路径。比如，如果你计划将你的站点部署到 `https://foo.github.io/bar/`，那么你应该将 `base` 设置为 `"/bar/"`：

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

export default defineConfig({
  doc: {
    base: '/bar/',
  },
  plugins: [docTools()],
});
```

## title

- Type: `string`
- Default: `"Island"`

站点标题。这个参数将被用作 HTML 页面的标题。例如：

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

export default defineConfig({
  doc: {
    title: '我的站点',
  },
  plugins: [docTools()],
});
```

## description

- Type: `string`
- Default: `""`

站点描述。这将用作 HTML 页面的描述。例如：

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

export default defineConfig({
  doc: {
    description: '我的站点描述',
  },
  plugins: [docTools()],
});
```

## icon

- Type: `string`
- Default: `""`

站点图标。这个路径将用作 HTML 页面的图标路径。例如：

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

export default defineConfig({
  doc: {
    icon: '/favicon.ico',
  },
  plugins: [docTools()],
});
```

框架会在 `public` 目录中找到你的图标，当然你也可以设置成一个 CDN 地址。

## logo

- Type: `string | { dark: string; light: string }`
- Default: `""`

站点 logo。这个路径将用作导航栏左上角的 logo 路径。例如：

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

export default defineConfig({
  doc: {
    logo: '/logo.png',
  },
  plugins: [docTools()],
});
```

框架会在 `public` 目录中找到你的图标，当然你也可以设置成一个 CDN 地址。

当然你可以针对浅色/暗黑模式设置不同的 logo：

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

export default defineConfig({
  doc: {
    logo: {
      dark: '/logo-dark.png',
      light: '/logo-light.png',
    },
  },
  plugins: [docTools()],
});
```

## outDir

- Type: `string`
- Default: `doc_build`

自定义构建站点的输出目录。比如:

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

export default defineConfig({
  doc: {
    outDir: 'doc_build',
  },
  plugins: [docTools()],
});
```

## locales

- Type: `Locale[]`

```ts
export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}
```

站点的多语言配置。比如：

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

export default defineConfig({
  doc: {
    locales: [
      {
        lang: 'en-US',
        label: 'English',
        title: 'Doc Tools',
        description: 'Doc Tools',
      },
      {
        lang: 'zh-CN',
        label: '简体中文',
        title: '文档框架',
        description: '文档框架',
      },
    ],
  },
  plugins: [docTools()],
});
```

## mediumZoom

- Type: `boolean` | `{ selector?: string }`
- Default: `true`

是否开启图片放大功能。默认开启，你可以通过设置 `mediumZoom` 为 `false` 来关闭。

> 底层使用的是 [medium-zoom](https://github.com/francoischalifour/medium-zoom) 库来实现的。

使用示例：

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

export default defineConfig({
  doc: {
    // 关闭图片放大功能
    mediumZoom: false,
    // 配置 CSS 选择器，自定义要放大的图片，默认为 '.modern-doc img'
    mediumZoom: {
      selector: '.modern-doc img',
    },
  },
  plugins: [docTools()],
});
```

## search

- Type: `{ searchHooks: string }`

你可以通过 `searchHooks` 参数来增加搜索运行时钩子逻辑，比如：

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

export default defineConfig({
  doc: {
    search: {
      searchHooks: path.join(__dirname, 'searchHooks.ts'),
    },
  },
  plugins: [docTools()],
});
```

`searchHooks.ts` 中，你需要导出 `onSearch` 函数，这个函数将会在每次搜索时被调用，入参为搜索关键词，你可以在这里自定义搜索拦截逻辑，比如：

```ts title="searchHooks.ts"
// 支持 async 函数
export async function onSearch(query: string) {
  // 执行自定义逻辑，比如打点上报
  console.log(query);
}
```

## globalUIComponents

- Type: `string[]`
- Default: `[]`

你可以通过 `globalUIComponents` 参数来增加全局 UI 组件，比如：

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

export default defineConfig({
  doc: {
    globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
  },
  plugins: [docTools()],
});
```

import GlobalUIComponents from '../../fragments/global-ui-components.mdx';

<GlobalUIComponents />