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

Website for @modern-js/doc-tools

# 主题配置

主题配置位于 `doc` 配置中的 `themeConfig` 下。例如：

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

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

## nav

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

网站的导航栏。 `nav` 配置是 `NavItem` 的数组，具有以下类型：

```ts
interface NavItem {
  // 导航栏文本
  text: string;
  // 导航栏链接
  link: '/';
  // 导航栏链接的激活规则
  activeMatch: '^/$|^/';
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}
```

`activeMatch` 用于匹配当前路由，当路由匹配 `activeMatch` 规则时，nav 项会高亮显示。默认情况下，`activeMatch` 是 nav 项的 `link`。

比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      nav: [
        {
          text: 'Home',
          link: '/',
        },
        {
          text: 'Guide',
          link: '/guide/',
        },
      ],
    },
  },
  plugins: [docTools()],
});
```

当然 `nav` 数组中也可以配置多级菜单，类型如下:

```ts
interface NavGroup {
  // 导航栏文本
  text: string;
  // 子菜单
  items: NavItem[];
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}
```

例如下面的配置:

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

export default defineConfig({
  doc: {
    themeConfig: {
      nav: [
        {
          text: 'Home',
          link: '/',
        },
        {
          text: 'Guide',
          items: [
            {
              text: 'Getting Started',
              link: '/guide/getting-started',
            },
            {
              text: 'Advanced',
              link: '/guide/advanced',
            },
          ],
        },
      ],
    },
  },
  plugins: [docTools()],
});
```

## sidebar

- Type: `Object`

网站的侧边栏。配置为一个对象，类型如下：

```ts
// key 为 SidebarGroup 的路径
// value 为 SidebarGroup 的数组
type Sidebar = Record<string, SidebarGroup[]>;

interface SidebarGroup {
  text: string;
  link?: string;
  items: SidebarItem[];
  // 是否可折叠
  collapsible?: boolean;
  // 是否默认折叠
  collapsed?: boolean;
  // 图标配置(可选)，填入 svg 标签内容或者图片 URL
  tag?: string;
}

// 可填入一个对象，也可以填入一个字符串
// 填入字符串时，内部会转换成一个对象，字符串会被当做 link，text 值会自动取对应文档的标题
type SidebarItem =
  | {
      // 侧边栏文本
      text: string;
      // 侧边栏链接
      link: string;
      // 图标配置(可选)，填入 svg 标签内容或者图片 URL
      tag?: string;
    }
  | string;
```

比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      sidebar: {
        '/guide/': [
          {
            text: 'Getting Started',
            items: [
              // 填入一个对象
              {
                text: 'Introduction',
                link: '/guide/getting-started/introduction',
              },
              {
                text: 'Installation',
                link: '/guide/getting-started/installation',
              },
            ],
          },
          {
            text: 'Advanced',
            items: [
              // 直接填入链接字符串
              '/guide/advanced/customization',
              '/guide/advanced/markdown',
            ],
          },
        ],
      },
    },
  },
  plugins: [docTools()],
});
```

## footer

- Type: `Object`
- Default: `{}`

主页的页脚。

`footer` 配置是 `Footer` 的一个对象，它具有以下类型：

```ts
export interface Footer {
  message?: string;
  copyright?: string;
}
```

比如：

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

export default defineConfig({
  doc: {
    themeConfig: {
      footer: {
        message: 'This is a footer',
      },
    },
  },
  plugins: [docTools()],
});
```

## outlineTitle

- Type: `string`
- Default: 'ON THIS PAGE'

在右侧边栏中配置大纲的标题。

比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      outlineTitle: 'Outline',
    },
  },
  plugins: [docTools()],
});
```

## lastUpdated

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

是否显示最后更新时间，默认情况下不显示。

比如:

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

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

## lastUpdatedText

- Type: `string`
- Default: `Last Updated`

最后更新时间的文本。

比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      lastUpdatedText: 'Last Updated',
    },
  },
  plugins: [docTools()],
});
```

## prevPageText

- Type: `string`
- Default: `Previous Page`

上一页的文本。比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      prevPageText: 'Previous Page',
    },
  },
  plugins: [docTools()],
});
```

## socialLinks

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

你可以通过如下的配置添加相关链接，比如 `github` 链接、`twitter` 链接等。
相关链接支持三种模式：`链接模式link` `文本模式text` `图片模式img`，相关例子如下：

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

export default defineConfig({
  doc: {
    themeConfig: {
      socialLinks: [
        {
          icon: 'github',
          mode: 'link',
          content: 'https://github.com/sanyuan0704/island.js',
        },
        {
          icon: 'wechat',
          mode: 'text',
          content: '微信号xxx',
        },
        {
          icon: 'qq',
          mode: 'img',
          content: '/qrcode.png',
        },
      ],
    },
  },
  plugins: [docTools()],
});
```

- 当`link`模式时，点击 icon 即可跳转链接。
- 当`text`模式时，鼠标移到 icon 上会显示弹框，弹框内容是输入的文本。
- 当`img`模式时，鼠标移到 icon 上会显示弹框，弹框内容是指定的图片，需要注意的是，图片需要放在`public`目录下。

相关链接支持以下几种图片，通过 icon 属性来选择：

```ts
export type SocialLinkIcon =
  | 'lark'
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'twitter'
  | 'youtube'
  | 'weixin'
  | 'qq'
  | 'juejin'
  | 'zhihu'
  | 'bilibili'
  | 'weibo'
  | 'gitlab'
  | { svg: string };
```

如果需要自定义 icon，可以通过传入一个带有`svg属性`的对象，svg 的值为自定义图标内容即可，比如：

```js
import { docTools, defineConfig } from '@modern-js/doc-tools';

export default defineConfig({
  doc: {
    themeConfig: {
      socialLinks: [
        {
          icon: {
            svg: 'svg图标内容',
          },
          mode: 'link',
          content: 'https://github.com/',
        },
      ],
    },
  }
  plugins: [docTools()],·
});
```

## nextPageText

- Type: `string`
- Default: `Next Page`

下一页的文本。比如:

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

export default defineConfig({
  doc: {
    themeConfig: {
      nextPageText: 'Next Page',
    },
  },
  plugins: [docTools()],
});
```

## locales

- Type: `Array<LocaleConfig>`
- Default: `undefined`

国际化配置。此配置为一个数组，数组中的每一项都是一个 `LocaleConfig` 对象，它具有以下类型：

```ts
export interface LocaleConfig {
  /**
   * 通用站点信息，优先级高于 `doc.locales` 中的配置
   */
  // 语言名称
  lang?: string;
  // HTML 标题，优先于 `themeConfig.title`
  title?: string;
  // HTML 描述，优先于 `themeConfig.description`
  description?: string;
  // 对应语言的显示文本
  label: string;
  /**
   * 主题相关信息
   */
  // 右侧大纲标题
  outlineTitle?: string;
  // 是否显示右侧大纲
  outline?: boolean;
  // 最后更新时间文本
  lastUpdatedText?: string;
  // 是否显示最后更新时间
  lastUpdated?: boolean;
  // 上一页文本
  prevPageText?: string;
  // 下一页文本
  nextPageText?: string;
}
```

`LocaleConfig` 中包含许多与主题配置中相同的配置项，但它的优先级会更高。

## darkMode

- Type: `boolean`
- Default: `true`

是否出现暗黑模式/白天模式切换按钮。比如：

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

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

## hideNavbar

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

用来隐藏导航栏。比如：

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

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