主题配置

在主题开发中，往往需要提供一些配置来丰富主题的功能，最简单的是和 Vitepress 的 themeConfig 配置合在一起：

// .vitepress/config.ts
import { defineConfig } from "vitepress";

export default defineConfig({
  // ...
  themeConfig: {
    // vitepress 配置
    // 自定义主题配置
  },
});

然后在组件里通过 useData 获取 themeConfig 的内容：

<script setup lang="ts">
import { useData } from "vitepress";

// 获取 themeConfig
const { theme } = useData;

// 获取自定义主题配置项
const xx = theme.value.xx;
</script>

<template></template>

这种方式仅适合简单的主题，当主题需要添加一个 head 或者 vite 插件，需要让用户修改 Vitepress 的配置，这样极其不方便。

因此可以先将主题配置抽离出来，然后使用 extends 来合并主题配置。

extends 合并配置

Vitepress 提供了 extends 来合并外界传来的配置项，比如外界的配置提供了部分 head 内容，并且在 Vitepress 也配置了 head，则最终合并为一个全新的 head，而不是覆盖。

提示

只有 Vitepress 的配置项为对象/数组时可以合并，如果配置项为一个固定的值或者函数，则以 Vitepress 的配置项为主。

extends 合并主题配置的使用方式如下：

import { defineConfig } from "vitepress";

// 主题配置
const teekConfig = {};

// vitepress 配置
export default defineConfig({
  extends: teekConfig,
  // ...
  themeConfig: {
    // ...
  },
});

在 Vitepress 配置中通过 extends 可以将主题配置合并到 Vitepress 配置里，也就是说完全可以在主题配置里添加 Vitepress 的配置项，但是不能反过来，如：

各自配置

// .vitepress/config.ts
import { defineConfig } from "vitepress";

// 主题配置
const myThemeConfig = { themeConfig: { tkTheme: true } };

// Vitepress 配置
export default defineConfig({
  extends: myThemeConfig,
  base: "/",
});

统一配置

// .vitepress/config.ts
import { defineConfig } from "vitepress";

// 主题配置 + Vitepress 配置
const myThemeConfig = { base: "/", themeConfig: { tkTheme: true } };

export default defineConfig({
  extends: myThemeConfig,
});

函数式构建配置

在主题配置里，如果要使用 Vite 插件或者想要修改 Vitepress 默认的配置，则可以提供一个函数来返回主题配置：

// myThemeConfig.ts
import type { DefaultTheme, UserConfig } from "vitepress";
import type { PluginOption } from "vite";

interface ThemeConfig {
  useTheme?: boolean; // 是否开启主题
  // ...
}

export default function getThemeConfig(config: ThemeConfig & UserConfig<DefaultTheme.Config> = {}): UserConfig {
  // 获取用户的配置，进行逻辑处理
  const { useTheme = true, ...themeConfig } = config;

  if (!useTheme) return {};

  return {
    // ignoreDeadLinks 默认值修改为 true，当用户在 Vitepress 手动改为 false 才为 false
    ignoreDeadLinks: true,
    // 添加主题需要的 head 信息
    head: [],
    vite: {
      // 添加主题需要的 Vite 插件
      plugins: [],
    },
    themeConfig,
  };
}

在 .vitepress/config.ts 引入该函数：

import { defineConfig } from "vitepress";
import getThemeConfig from "myThemeConfig";

const myThemeConfig = getThemeConfig({ useTheme: false });

// Vitepress 配置
export default defineConfig({
  extends: myThemeConfig,
  // ...
});