J

主题

2025-03-092025-07-03配置配置
2852
12.6m
Get...

全局配置 ​

全局配置是影响范围较广的配置。

teekTheme ​

  • 类型：boolean
  • 默认值：true

是否启用主题，如果为 false，则不会启用主题的 99% 功能，只保留如下功能：

  • 自动添加侧边栏
  • 自动添加一级标题
  • 自动添加永久链接
  • 文档内容分析（作者、创建时间、文章字数、预计阅读时间等信息）
  • 锚点滚动
  • 深色/浅色模式过渡动画

提示

如果您仍然想要关闭这些部分功能，Teek 也提供了相关配置项来关闭。

配置如下：

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  teekTheme: true,
});

提示

如果想全部清除 Teek 的功能，那么在 .vitepress/theme/index.ts 文件里去掉 Teek 引用。

teekHome ​

  • 类型：boolean
  • 默认值：true

是否启用 Teek 的首页风格，如果为 false，则还原到 VitePress 的默认首页，其他功能不变。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  teekHome: true,
});
yaml
---
tk:
  teekHome: true
---

vpHome ​

  • 类型：boolean
  • 默认值：true

是否启用 VitePress 首页风格，支持 teekHome 和 vpHome 同时存在。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vpHome: true,
});
yaml
---
tk:
  vpHome: true
---

homeCardListPosition v1.2.0 ​

  • 类型：left | right
  • 默认值：right

首页卡片栏列表位置，当为 left 则在文章列表左侧，当为 right 则在文章列表右侧。

config.mts
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  homeCardListPosition: "right",
});

anchorScroll ​

  • 类型：boolean
  • 默认值：true

是否启用锚点滚动功能，即阅读文章时，自动将 h1 ~ h6 标题添加到地址栏 # 后面。

config.mts
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  anchorScroll: true,
});

viewTransition ​

  • 类型：boolean
  • 默认值：true

深色、浅色模式切换时是否开启过渡动画。

config.mts
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  viewTransition: true,
});

themeSize ​

  • 类型：small | default | large | wide
  • 默认值：default

配置主题尺寸。只影响 Teek 主题首页和功能页，不影响 VitePress 默认主题。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  themeSize: "large",
});

backTopDone ​

  • 类型：(TkMessage: Message) => void

右下角回到顶部按钮的回调，可以利用 TkMessage 的方法如 TkMessage.success("返回顶部成功") 进行提示。

config.mts
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  backTopDone: TkMessage => TkMessage.success("返回顶部成功"),
});

toCommentDone ​

  • 类型：(TkMessage: Message) => void

右下角滚动到评论按钮的回调，使用方式于 backTopDone 一样。

config.mts
ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  toCommentDone: TkMessage => TkMessage.success("已抵达评论区"),
});

codeBlock ​

新版代码块配置，在 details 容器下恢复为默认代码块风格。

提示

Teek 文档使用的是新版代码块。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  codeBlock: {
    disabled: false, // 是否禁用新版代码块
    collapseHeight: 700, // 超出高度后自动折叠，设置 true 则默认折叠，false 则默认不折叠
    copiedDone: (TkMessage: Message) => TkMessage.success("复制成功！"),
  },
});
yaml
---
codeBlock:
  disabled: false
  collapseHeight: 700
---
ts
interface CodeBlock {
  /**
   * 是否禁用新版代码块
   *
   * @default false
   */
  disabled?: boolean;
  /**
   * 超出高度后自动折叠，设置 true 则默认折叠，false 则默认不折叠
   *
   * @default 700
   */
  collapseHeight?: number | boolean;
  /**
   * 复制代码完成后的回调
   */
  copiedDone?: (TkMessage: Message) => void;
}

新版代码块的语言默认为大写，如果希望为小写或者首字母大写，通过修改 css var 的 tk-code-block-lang-transform 来达成目标。

提示

tk-code-block-lang-transform 的值等于 CSS 中 text-transform 的值。

先定义一个 css 文件：

tk-code-style.css
css
/* .vitepress/theme/style/tk-code-style.css */
:root {
  /*
   * none：文本中的单词保持默认风格
   * capitalize：文本中的每个单词以大写字母开头
   * lowercase：文本中的每个单词全部转为小写
   * uppercase：定文本中的单次全部转为大写
   */
  tk-code-block-lang-transform: lowercase;
}

在 .vitepress/theme/index.ts 文件引入该 css 文件：

ts
// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import "./style/tk-code-style.css";

export default {
  extends: Teek,
};

bodyBgImg ​

body 背景图片配置，将整个网站的背景色改为图片。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  bodyBgImg: {
    imgSrc: ["/img/bg1.jpg", "/img/bg2.png"], // body 背景图片链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
    imgOpacity: 1, // body 背景图透明度，选值 0.1 ~ 1.0
    imgInterval: 15000, //  body 当多张背景图时（imgSrc 为数组），设置切换时间，单位：毫秒
    imgShuffle: false, // body 背景图是否随机切换，为 false 时按顺序切换
    mask: false, // body 背景图遮罩
    maskBg: "rgba(0, 0, 0, 0.2)", // body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
  };
});
yaml
---
bodyBgImg:
  imgSrc:
    - /img/bg1.jpg
    - /img/bg2.png
  imgOpacity: 1
  imgInterval: 15000
  imgShuffle: false
  mask: false
  maskBg: "rgba(0, 0, 0, 0.2)"
---
ts
interface BodyBgImg {
  /**
   * body 背景图片链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
   */
  imgSrc?: string | string[];
  /**
   * body 背景图透明度，选值 0.1 ~ 1.0
   *
   * @default 1
   */
  imgOpacity?: 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
  /**
   * body 当多张背景图时（imgSrc 为数组），设置切换时间，单位：毫秒
   *
   * @default 15000 (15秒)
   */
  imgInterval?: number;
  /**
   * body 背景图是否随机切换，为 false 时按顺序切换
   *
   * @default false
   */
  imgShuffle?: boolean;
  /**
   * body 背景图遮罩
   *
   * @default false
   */
  mask?: boolean;
  /**
   * body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
   *
   * @default 'rgba(0, 0, 0, 0.2)'
   */
  maskBg?: string | number;
}

提示

bodyBgImg 设置了 imgSrc 后，banner 的图片风格会失效。

themeEnhance v1.1.0 ​

主题增强配置，当开启后，右上角将有主题增强面板出现。

关于如何使用请看 主题增强，关于如何拓展自定义主题请看 主题增强拓展。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  themeEnhance: {
    position: "top", // 位置，top 为导航栏右侧，bottom 为右下角
    // 布局切换配置
    layoutSwitch: {
      disabled: false,
      defaultMode: "original"
    },
    // 布局主题色配置
    themeColor: {
      disabled: false,
      defaultColor: "vp-default",
      defaultSpread: false
    },
    // 聚光灯配置
    spotlight: {
      disabled: false,
      defaultStyle: "aside",
      defaultValue: true
    }
  };
});
ts
import type { ThemeColor, LayoutMode, SpotlightStyle } from "vitepress-theme-teek";

interface ThemeEnhance {
  /**
   * 位置，top 为导航栏右侧，bottom 为右下角
   *
   * @default 'top'
   */
  position?: "top" | "bottom";
  /**
   * 布局切换配置
   */
  layoutSwitch?: {
    /**
     * 禁用布局切换
     */
    disabled?: boolean;
    /**
     * 布局切换的默认模式
     *
     * @default LayoutMode.Original
     */
    defaultMode?: LayoutMode | "fullWidth" | "sidebarWidthAdjustableOnly" | "bothWidthAdjustable" | "original";
    /**
     * 切换布局成功后的回调
     *
     * @since 1.3.2
     */
    switchModeDone?: (
      mode: LayoutMode | "fullWidth" | "sidebarWidthAdjustableOnly" | "bothWidthAdjustable" | "original"
    ) => void;
    /**
     * 禁用帮助提示
     *
     * @default false
     */
    disableHelp?: boolean;
    /**
     * 禁用布局切换动画
     */
    disableAnimation?: boolean;
    /**
     * 内容布局最大宽度的默认百分比，仅限 0-100
     *
     * @default 90 (90%)
     */
    defaultDocMaxWidth?: number;
    /**
     * 禁用帮助提示
     *
     * @default false
     */
    disableDocMaxWidthHelp?: boolean;
    /**
     * 页面布局最大宽度的默认百分比，仅限 0-100
     *
     * @default 95 (95%)
     */
    defaultPageMaxWidth?: number;
    /**
     * 禁用帮助提示
     *
     * @default false
     */
    disablePageMaxWidthHelp?: boolean;
  };
  /**
   * 布局主题色配置
   */
  themeColor?: {
    /**
     * 禁用布局主题色切换
     *
     * @default false
     */
    disabled?: boolean;
    /**
     * 布局默认主题色
     *
     * @default ThemeColor.vpDefault
     */
    defaultColor?:
      | ThemeColor
      | "vp-default"
      | "vp-green"
      | "vp-yellow"
      | "vp-red"
      | "ep-blue"
      | "ep-green"
      | "ep-yellow"
      | "ep-red";
    /**
     * 切换布局成功后的回调
     *
     * @since 1.3.2
     */
    switchColorDone?: (color: string) => void;
    /**
     * 是否将主题色扩散到其他元素（根据主题色计算其他元素需要的颜色）
     *
     * @default false
     */
    defaultSpread?: boolean;
    /**
     * 禁用帮助提示
     *
     * @default false
     */
    disableHelp?: boolean;
    /**
     * 是否在移动端禁用
     *
     * @default false
     */
    disabledInMobile?: boolean;
    /**
     * 自定义主题色，将会追加到内置主题色后面
     */
    append?: {
      /**
       * 主题组名称
       */
      label: string;
      /**
       * 主题组提示信息，鼠标悬停时显示
       */
      tip?: string;
      /**
       * 主题组内容
       */
      options: {
        /**
         * 主题名称，用于页面文字渲染
         */
        label: string;
        /**
         * 主题标识，在 html 标签的 theme 属性添加该标识
         */
        value: string;
      }[];
    }[];
  };
  /**
   * 聚光灯配置
   */
  spotlight?: {
    /**
     * 禁用聚光灯
     *
     * @default false
     */
    disabled?: boolean;
    /**
     * 聚光灯默认样式
     *
     * @default SpotlightStyle.Aside
     */
    defaultStyle?: SpotlightStyle | "aside" | "under";
    /**
     * 禁用帮助提示
     *
     * @default false
     */
    disableHelp?: boolean;
    /**
     * 聚光灯默认开关状态
     *
     * @default true
     */
    defaultValue?: boolean;
  };
}

author ​

文章默认的作者信息。

在首页的文章列表和文章页使用该功能。

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  author: {
    name: "Teeker", // 作者名称
    link: "https://github.com/Kele-Bingtang", // 点击作者名称后跳转的链接
  };
});
yaml
---
author:
  name: "Teeker"
  link: "https://github.com/Kele-Bingtang",
---
ts
interface Author {
  /**
   * 作者名称，作用在首页的 PostItem 和文章页
   */
  name: string;
  /**
   * 点击作者名称后跳转的链接
   */
  link?: string;
}

notice ​

公告配置。

公告组件只提供基础功能，不提供任何内容的渲染，需要您自定义组件，然后在 .vitepress/theme/index.ts 中通过 teek-notice-content 插槽传进来。

使用如下：

插槽
ts
// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import MyNoticeContent from "./components/MyNoticeContent.vue";
import { h } from "vue";

export default {
  extends: Teek,
  Layout() {
    return h(Teek.Layout, null, {
      "teek-notice-content": () => h(MyNoticeContent),
    });
  },
};

配置如下：

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  notice: {
    enabled: true, // 是否启用公告功能
    title: "公告", // 公告标题，支持函数式：需要和国际化搭配使用，根据不同语言环境返回不同标题
    initOpen: true,
    duration: 0, // 弹框定时自动关闭，0 不自动消失
    mobileMinify: false, // 移动端自动最小化
    reopen: true,
    useStorage: true, // 是是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
    twinkle: false, // 公告图标是否打开闪烁提示
    position: "top", // 公告弹框出现位置
    // ...
  },
});
yaml
---
notice:
  enabled: true
  title: "公告"
  initOpen: true
  duration: 0
  mobileMinify: false
  reopen: true
  useStorage: true
  twinkle: false
  position: "top"
---
ts
import type { Route } from "vitepress";
import type { IconProps } from "vitepress-theme-teek";

interface Notice {
  /**
   * 是否启用公告功能
   *
   * @default false
   */
  enabled?: boolean;
  /**
   * 公告自定义全局样式
   *
   * @example
   * ```css
   * .tk-notice a {
   *    color: var(--vp-c-brand-2);
   * }
   * ```
   */
  noticeStyle?: string;
  /**
   * 公告图标样式
   */
  iconStyle?: Record<string, any>;
  /**
   * 公告弹窗样式
   */
  popoverStyle?: Record<string, any>;
  /**
   * 公告标题，函数式需要和国际化搭配使用，根据不同语言环境返回不同标题
   *
   * @default '公告'
   */
  title?: string | ((localeIndex: string) => string);
  /**
   * 第一次进入页面，是否默认打开公告弹框
   *
   * @default true
   */
  initOpen?: boolean;
  /**
   * 弹框定时自动关闭，0 不自动消失
   *
   * @default 0
   */
  duration?: number;
  /**
   * 移动端自动最小化
   *
   * @default false
   */
  mobileMinify?: boolean;
  /**
   * 关闭公告弹框后，是否支持重新打开，如果为 false，则代表公告只显示一次
   *
   * @default true
   */
  reopen?: boolean;
  /**
   * 是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
   */
  useStorage?: boolean;
  /**
   * 公告图标是否打开闪烁提示
   *
   * @default false
   */
  twinkle?: boolean;
  /**
   * 公告弹框出现位置
   *
   * @default top
   */
  position?: "top" | "center";
  /**
   * 公告图标地址
   *
   * @remark 与 noticeIconType 配合使用
   */
  noticeIcon?: IconProps["icon"];
  /**
   * 公告弹框关闭图标地址，与 noticeIcon 配置一致
   */
  closeIcon?: IconProps["icon"];
  /**
   * 路由切换后的自定义回调
   *
   * @param to 切换到的目标路由
   */
  onAfterRouteChange?: (to: Route, noticeShow: boolean, showPopover: boolean) => void;
}

siteAnalytics ​

站点分析配置，目前集成了三种常见的站点统计工具：

  • 百度分析 Baidu Analytics
  • 谷歌分析 Google Analytics
  • Umami 分析

具体使用说明请看 站点统计。

使用如下：

ts
// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  siteAnalytics: [
    {
      provider: "google",
      options: {
        id: "******",
      },
    },
    {
      provider: "baidu",
      options: {
        id: "******",
      },
    },
    {
      provider: "umami",
      options: {
        id: "******",
        src: "**",
      },
    },
  ],
});
ts
import type { BaiduAnalyticsOptions, GoogleAnalyticsOptions, UmamiAnalyticsOptions } from "vitepress-theme-teek";

type SiteAnalytics<T extends keyof SiteAnalyticsProvider = ""> = {
  /**
   * 赞赏位置
   */
  provider: T;
  /**
   * 赞赏配置
   */
  options?: SiteAnalyticsProvider[T];
};

type SiteAnalyticsProvider = {
  "": object;
  baidu: BaiduAnalyticsOptions;
  google: GoogleAnalyticsOptions;
  umami: UmamiAnalyticsOptions;
};
最近更新