全局配置

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

teekTheme

类型：boolean
默认值：true

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

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

提示

如果您仍然想要关闭保留的部分功能，Teek 也提供了相关配置项来关闭，请继续往下阅读保留功能的配置项。

配置如下：

// .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 的默认首页，其他功能不变。

config.mtsindex.md

// .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 同时存在。

config.mtsindex.md

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

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

yaml

---
tk:
  vpHome: true
---

loading v1.4.1

类型：boolean | string
默认值：true

页面加载 Loading 动画配置，如果为 boolean，则控制是否启用，如果为字符串，则指定加载 Loading 动画的文案。

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

const teekConfig = defineTeekConfig({
  loading: true, // 启用 Loading 动画，为 false 则关闭 Loading 动画
  // loading: "正在加载中...", // 修改 Loading 文案
});

features v1.4.1

站点特性列表，在文档风格的首页展渲染，与 VitePress 的 features 配置模板一致，但是不会与 VitePress 的 features 配置渲染冲突。

该配置项 Teek 建议在首页 index.md 文档里的 frontmatter.tk.features 进行配置。

每一个 feature 的 icon 为 TkIcon Props 的 icon 属性，支持传入 iconfont、SVG、图片等图标。

index.mdconfig.mts更多配置项

yaml

tk:
  teekHome: false
  features:
    - title: 快速开发
      details: 提供了完整版参考代码和精简版开发代码
      image: /feature/ui.svg
      highlights:
        - title: 从零安装：运行 <code>pnpm add vitepress-theme-teek vitepress</code> 以从 NPM 下载 Teek 主题。
        - title: 现有模板：运行 <code>git clone https://github.com/Kele-Bingtang/vitepress-theme-teek-docs-template.git</code> 以下载当前文档模板。

    - title: 拥有丰富的 Features，并持续更新
      details: 满足大部分开发场景。
      image: /feature/features.svg
      features:
        - title: 最新流行稳定技术栈
          icon: icon-github
          details: 基于 Vue3.2、TypeScript、Vite4、Pinia、Element-Plus 等最新技术栈开发
          link: /guide/intro

        - title: 简单上手 & 学习
          icon: <svg viewBox="0 0 24 24" width="1.2em" height="1.2em"><path fill="currentColor" d="m23 12l-7.071 7.071l-1.414-1.414L20.172 12l-5.657-5.657l1.414-1.414L23 12zM3.828 12l5.657 5.657l-1.414 1.414L1 12l7.071-7.071l1.414 1.414L3.828 12z"></path></svg>
          details: 项目结构清晰，代码简单、易读。

        - title: 规范工程化工作流
          icon: /teek-logo-mini.svg
          details: 配置 Eslint、Prettier、Husky、Commitlint、Lint-staged 规范前端工程代码规范。

        - title: 完善的打包优化方案
          icon: icon-github
          details: 内置规范的打包目录，提供打包压缩功能，减少打包体积。

        - title: 丰富的组件
          icon: /teek-logo-mini.svg
          details: 提供丰富的通用组件、业务组件。
          link: /ecosystem/components

        - title: 常用 Hook 函数
          icon: icon-gitee
          details: 提供丰富的组件、常用 Hooks 封装，实现复用思想，减少重复开发，提高效率。

        - title: 个性化主题配置
          icon: icon-xiangce
          details: 提供主题颜色配置，暗黑、灰色、色弱等模式切换。
          link: /guide/theme-enhance

        - title: 多种布局配置
          icon: /teek-logo-mini.svg
          details: 提供多种布局、标签栏切换，布局显隐，满足大部分场景。

        - title: 项目权限管控
          icon: /teek-logo-mini.svg
          details: 采用 RBAC 权限管控，提供菜单、路由及按钮粗细粒度权限管理方案

        - title: 国际化
          icon: /teek-logo-mini.svg
          details: 内置常用国际化转换函数，支持自定义国际化切换，

        - title: IFrame 嵌入
          icon: /teek-logo-mini.svg
          details: 提供 IFrame 嵌入、缓存功能，支持门户 Portal 布局。

        - title: 自定义指令
          icon: /teek-logo-mini.svg
          details: 内置多种 Vue 自定义指令，提供傻瓜式指令一键注册功能。

        - title: Axios 封装
          icon: /teek-logo-mini.svg
          details: 基于 Axios 封装常用请求模块，内置业务拦截器、异常拦截器。

        - title: 多种图标类型
          icon: /teek-logo-mini.svg
          details: 支持 IconFont、SVG、Iconify 等多种图标类型渲染。
          link: /guide/icon-use

    - title: 布局
      details: 多种布局、标签栏切换，布局组件显隐
      image: /feature/layout.svg
      highlights:
        - title: 六大布局
          icon: /teek-logo-mini.svg
          details: 内置纵向、经典、横向、分栏、混合、子系统六大布局切换

        - title: 深色模式
          icon: /teek-logo-mini.svg
          details: 可以自由切换浅色模式与深色模式

        - title: 主题色切换
          icon: /teek-logo-mini.svg
          details: 支持自定义主题色并允许用户在预设的主题颜色之间切换

        - title: 布局组件
          icon: /teek-logo-mini.svg
          details: 支持图标、面包屑、导航栏等组件显隐，内置缓存功能，记住用户的布局配置

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

const teekConfig = defineTeekConfig({
  features: [
    {
      title: "快速开发",
      details: "提供了完整版参考代码和精简版开发代码",
      image: "/feature/ui.svg",
      highlights: [
        {
          title: "从零安装：运行 <code>pnpm add vitepress-theme-teek vitepress</code> 以从 NPM 下载 Teek 主题。",
        },
        {
          title:
            "现有模板：运行 <code>git clone https://github.com/Kele-Bingtang/vitepress-theme-teek-docs-template.git</code> 以下载当前文档模板。",
        },
      ],
    },
    {
      title: "拥有丰富的 Features，并持续更新",
      details: "满足大部分开发场景。",
      image: "/feature/features.svg",
      features: [
        {
          title: "最新流行稳定技术栈",
          icon: "icon-github",
          details: "基于 Vue3.2、TypeScript、Vite4、Pinia、Element-Plus 等最新技术栈开发",
          link: "/guide/intro",
        },
        {
          title: "简单上手 & 学习",
          icon: '<svg viewBox="0 0 24 24" width="1.2em" height="1.2em"><path fill="currentColor" d="m23 12l-7.071 7.071l-1.414-1.414L20.172 12l-5.657-5.657l1.414-1.414L23 12zM3.828 12l5.657 5.657l-1.414 1.414L1 12l7.071-7.071l1.414 1.414L3.828 12z"></path></svg>',
          details: "项目结构清晰，代码简单、易读。",
        },
        {
          title: "规范工程化工作流",
          icon: "/teek-logo-mini.svg",
          details: "配置 Eslint、Prettier、Husky、Commitlint、Lint-staged 规范前端工程代码规范。",
        },
        {
          title: "完善的打包优化方案",
          icon: "icon-github",
          details: "内置规范的打包目录，提供打包压缩功能，减少打包体积。",
        },
        {
          title: "丰富的组件",
          icon: "/teek-logo-mini.svg",
          details: "提供丰富的通用组件、业务组件。",
          link: "/ecosystem/components",
        },
        {
          title: "常用 Hook 函数",
          icon: "icon-gitee",
          details: "提供丰富的组件、常用 Hooks 封装，实现复用思想，减少重复开发，提高效率。",
        },
        {
          title: "个性化主题配置",
          icon: "icon-xiangce",
          details: "提供主题颜色配置，暗黑、灰色、色弱等模式切换。",
          link: "/guide/theme-enhance",
        },
        {
          title: "多种布局配置",
          icon: "/teek-logo-mini.svg",
          details: "提供多种布局、标签栏切换，布局显隐，满足大部分场景。",
        },
        {
          title: "项目权限管控",
          icon: "/teek-logo-mini.svg",
          details: "采用 RBAC 权限管控，提供菜单、路由及按钮粗细粒度权限管理方案",
        },
        {
          title: "国际化",
          icon: "/teek-logo-mini.svg",
          details: "内置常用国际化转换函数，支持自定义国际化切换，",
        },
        {
          title: "IFrame 嵌入",
          icon: "/teek-logo-mini.svg",
          details: "提供 IFrame 嵌入、缓存功能，支持门户 Portal 布局。",
        },
        {
          title: "自定义指令",
          icon: "/teek-logo-mini.svg",
          details: "内置多种 Vue 自定义指令，提供傻瓜式指令一键注册功能。",
        },
        {
          title: "Axios 封装",
          icon: "/teek-logo-mini.svg",
          details: "基于 Axios 封装常用请求模块，内置业务拦截器、异常拦截器。",
        },
        {
          title: "多种图标类型",
          icon: "/teek-logo-mini.svg",
          details: "支持 IconFont、SVG、Iconify 等多种图标类型渲染。",
          link: "/guide/icon-use",
        },
      ],
    },
    {
      title: "布局",
      details: "多种布局、标签栏切换，布局组件显隐",
      image: "/feature/layout.svg",
      highlights: [
        {
          title: "六大布局",
          icon: "/teek-logo-mini.svg",
          details: "内置纵向、经典、横向、分栏、混合、子系统六大布局切换",
        },
        {
          title: "深色模式",
          icon: "/teek-logo-mini.svg",
          details: "可以自由切换浅色模式与深色模式",
        },
        {
          title: "主题色切换",
          icon: "/teek-logo-mini.svg",
          details: "支持自定义主题色并允许用户在预设的主题颜色之间切换",
        },
        {
          title: "布局组件",
          icon: "/teek-logo-mini.svg",
          details: "支持图标、面包屑、导航栏等组件显隐，内置缓存功能，记住用户的布局配置",
        },
      ],
    },
  ],
});

import type { IconProps } from "@teek/components/common/Icon/src/icon";

interface Feature {
  /**
   * 标题
   */
  title: string;
  /**
   * 描述
   */
  details?: string;
  /**
   * 图片地址
   */
  image?: string;
  /**
   * Features 数据
   */
  features?: FeatureItem[];
  /**
   * Highlights 数据
   */
  highlights?: FeatureItem[];
}

interface FeatureItem {
  /**
   * 标题
   */
  title: string;
  /**
   * 描述
   */
  details?: string;
  /**
   * 图标地址
   */
  icon?: IconProps["icon"];
  /**
   * 点击跳转链接
   */
  link?: string;
}

anchorScroll

类型：boolean
默认值：true

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

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

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

themeSize

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

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

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

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

如果你认为这些主题尺寸不够用，你可以自定义主题尺寸。

下面是 themeSize 为 default 时的的样式，你可以复制到一个 css 文件里，然后修改并在 .vitepress/theme/index.ts 文件中引入，这就会覆盖默认的样式。

css

:root,
html[#{$namespace}-theme-size="default"] {
  --tk-home-max-width: 1140px;
  --tk-home-gap: 20px;
  --tk-home-post-simple-img-width: 120px;
  --tk-home-post-simple-img-height: 80px;
  --tk-home-post-full-img-width: 360px;
  --tk-home-post-full-img-height: 100%;
  --tk-home-post-line-clamp: 3;
  --tk-home-card-padding: 10px;
  --tk-home-card-width: 280px;
  --tk-home-card-svg-margin-left: 5px;
  --tk-home-card-border-radius: 4px;
  --tk-home-font-size-large: 18px;
  --tk-home-font-size-base: 16px;
  --tk-home-font-size-middle: 14px;
  --tk-home-font-size-sm: 13px;
  --tk-home-font-size-small: 12px;
  --tk-page-width: 900px;
  --tk-home-footer-group-width: 80%;
}

如果您认为首页的文章列表和卡片栏在高尺寸的屏幕显得很窄，则可以单独修改 --tk-home-max-width 来达到效果，如：

css

:root {
  --tk-home-max-width: calc(100% - 100% / 3); // 这里给的是一个响应式公式，100% 为屏幕宽度，请自行修改为自己认为合适的大小
}

记得在 .vitepress/theme/index.ts 文件中引入生效。

viewTransition v1.5.0

深色、浅色模式切换过渡动画配置。

config.mts更多配置项

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

const teekConfig = defineTeekConfig({
  viewTransition: {
    enabled: true, // 是否启用深浅色切换动画效果
    mode: "out-in", // 动画模式，out 始终从点击点往全屏扩散，out-in 第一次从点击点往全屏扩散，再次点击从全屏回到点击点
    duration: 300, // 动画持续时间，当 mode 为 out 时，默认为 300ms，mode 为 out-in 时，默认为 600ms
    easing: "ease-in", // 缓动函数
  },
});

interface ViewTransition {
  /**
   * 是否启用深浅色切换动画效果
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 动画模式，out 始终从点击点往全屏扩散，out-in 第一次从点击点往全屏扩散，再次点击从全屏回到点击点
   *
   * @default 'out-in'
   */
  mode?: "out" | "out-in";
  /**
   * 动画持续时间，当 mode 为 out 时，默认为 300ms，mode 为 out-in 时，默认为 600ms
   *
   * @default 'out-in: 300ms, out-in: 600ms'
   */
  duration?: number;
  /**
   * 缓动函数
   *
   * @default 'ease-in'
   */
  easing?: string;
}

backTop v1.4.0

右下角回到顶部配置。

如果希望将实时数字换成一个火箭图标，则将 backTop.content 设置为 icon。

config.mts更多配置项

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

const teekConfig = defineTeekConfig({
  backTop: {
    enabled: true, // 是否启动回到顶部功能
    content: "progress", // 回到顶部按钮的显示内容，可选配置 progress | icon
    done: TkMessage => TkMessage.success("返回顶部成功"), // 回到顶部后的回调
  },
});

import { Message } from "@teek/components/common/Message/src/message";

interface BackTop {
  /**
   * 是否启动回到顶部功能
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 回到顶部按钮的显示内容
   *
   * @default 'progress'
   */
  content?: "progress" | "icon";
  /**
   * 回到顶部后的回调
   */
  done?: (TkMessage: Message) => void;
}

如果想重写回到顶部的组件，则使用 teek-back-top 插槽。

toComment v1.4.0

右下角滚动滚动到评论区配置。

config.mts更多配置项

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

const teekConfig = defineTeekConfig({
  toComment: {
    enabled: true, // 是否启动滚动到评论区功能
    done: TkMessage => TkMessage.success("已抵达评论区"), // 滚动到评论区后的回调
  },
});

import { Message } from "@teek/components/common/Message/src/message";

interface ToComment {
  /**
   * 是否启动滚动到评论区功能
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 滚动到评论区后的回调
   */
  done?: (TkMessage: Message) => void;
}

如果想重写滚动滚动到评论区的组件，则使用 teek-to-comment 插槽。

codeBlock

新版代码块配置，您现在看到的代码块是新版代码块。

提示

在 details 容器下或父元素的 class 为 tk-vp-code 时，恢复为 VitePress 的默认代码块风格。

config.mts文章页 xxx.md更多配置项

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

const teekConfig = defineTeekConfig({
  codeBlock: {
    enabled: true, // 是否启用新版代码块
    collapseHeight: 700, // 超出高度后自动折叠，设置 true 则默认折叠，false 则默认不折叠
    overlay: false, // 代码块底部是否显示展开/折叠遮罩层
    overlayHeight: 400, // 当出现遮罩层时，指定代码块显示高度，当 overlay 为 true 时生效
    langTextTransform: "uppercase", // 语言文本显示样式，为 text-transform 的值:none, capitalize, lowercase, uppercase
    copiedDone: TkMessage => TkMessage.success("复制成功！"), // 复制代码完成后的回调
  },
});

yaml

---
codeBlock:
  disabled: false
  collapseHeight: 700
---

interface CodeBlock {
  /**
   * 是否启用新版代码块
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 超出高度后自动折叠，设置 true 则默认折叠，false 则默认不折叠
   *
   * @default 700
   */
  collapseHeight?: number | boolean;
  /**
   * 复制代码完成后的回调
   */
  copiedDone?: (TkMessage: Message) => void;
  /**
   * 代码块底部是否显示展开/折叠遮罩层
   *
   * @default false
   * @since 1.4.0
   */
  overlay?: boolean;
  /**
   * 当出现遮罩层时，指定代码块显示高度，当 overlay 为 true 时生效
   *
   * @default 400
   * @since 1.4.0
   */
  overlayHeight?: number;
  /**
   * 语言文本显示样式，为 text-transform 的值
   *
   * none：文本中的单词保持默认风格
   * capitalize：文本中的每个单词以大写字母开头
   * lowercase：文本中的每个单词全部转为小写
   * uppercase：定文本中的单次全部转为大写
   *
   * @default 'uppercase'
   */
  langTextTransform?: "none" | "capitalize" | "lowercase" | "uppercase";
}

新版代码块的语言默认为大写，如果希望为小写或者首字母大写，有两种方式：

通过在 config.mts 配置 codeBlock.langTextTransform，其原理是内部实现第二种方式来达到目标
通过修改 css var 变量的 tk-code-block-lang-transform 来达成目标

提示

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

先定义一个 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 文件：

// .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,
};

sidebarTrigger v1.4.0

类型：boolean
默认值：false

是否启用侧边栏展开/折叠触发器，点击触发器可以展开/折叠侧边栏。

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

const teekConfig = defineTeekConfig({
  sidebarTrigger: false,
});

如果想重写侧边栏展开/折叠触发器组件，则使用 teek-sidebar-trigger 插槽。

windowTransition v1.4.1

类型：boolean / object
默认值：true

是否全局给部分元素启用视图渐入过渡效果，当为 boolean 类型，则控制全局是否启用，当为 object 类型，则控制部分元素是否启用。

object 为 WindowTransition 类型，请看下方代码块的更多配置项。

什么是视图渐入过渡效果

当第一次进入博客风格的首页或者归档页时，向下滚动，会看到每一个元素的从下方向上移动的过渡效果。

config.mts更多配置项

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

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

interface TeekConfig {
  /**
   * 是否全局启用视图渐入过渡效果
   *
   * @default true
   */
  windowTransition?: boolean | WindowTransition;
}

interface WindowTransition {
  /**
   * 是否开启首页文章列表过渡效果
   *
   * @default false
   */
  post?: boolean;
  /**
   * 是否开启首页卡片列表过渡效果
   *
   * @default false
   */
  card?: boolean;
  /**
   * 是否开启归档页过渡效果
   *
   * @default false
   */
  archives?: boolean;
}

bodyBgImg

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

config.mts文章页 xx.md更多配置项

// .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)"
---

interface BodyBgImg {
  /**
   * body 背景图片链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
   */
  imgSrc?: string | string[] | (() => 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

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

关于主题增强详细的介绍请看主题增强。

config.mts更多配置项

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

const teekConfig = defineTeekConfig({
  themeEnhance: {
    enabled: true, // 启用主题增强功能
    position: "top", // 位置，top 为导航栏右侧，bottom 为右下角
    // 布局切换配置
    layoutSwitch: {
      disabled: false, // 禁用布局切换
      defaultMode: "original", // 布局切换的默认模式
      disableHelp: false, // 禁用帮助提示
      disableAnimation: false, // 禁用布局切换动画
      defaultDocMaxWidth: 90, // 内容布局最大宽度的默认百分比，仅限 0-100
      disableDocMaxWidthHelp: false, // 禁用帮助提示
      defaultPageMaxWidth: 95, // 页面布局最大宽度的默认百分比，仅限 0-100
      disablePageMaxWidthHelp: false, // 禁用帮助提示
    },
    // 布局主题色配置
    themeColor: {
      disabled: false, // 禁用布局主题色切换
      defaultColorName: "vp-default", // 布局默认主题色
      defaultSpread: false, // 是否将主题色扩散到其他元素（根据主题色计算其他元素需要的颜色）
      disableHelp: false, // 禁用帮助提示
      disabledInMobile: false, // 是否在移动端禁用
    },
    // 聚光灯配置
    spotlight: {
      disabled: false, // 禁用聚光灯
      defaultStyle: "aside", //  聚光灯默认样式
      disableHelp: false, // 禁用帮助提示
      defaultValue: true, // 聚光灯默认开关状态
    },
  },
});

import type { ThemeColorName, LayoutMode, SpotlightStyle } from "vitepress-theme-teek";

interface ThemeEnhance {
  /**
   * 启用主题增强功能
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * 位置，top 为导航栏右侧，bottom 为右下角
   *
   * @default 'top'
   */
  position?: "top" | "bottom";
  /**
   * 布局切换配置
   */
  layoutSwitch?: {
    /**
     * 禁用布局切换
     *
     * @default false
     */
    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;
    /**
     * 禁用布局切换动画
     *
     * @default false
     */
    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;
    /**
     * 从 0 完全自定义布局主题色，不使用内置主题色
     *
     * @default false
     * @since 1.4.1
     */
    customize?:
      | boolean
      | {
          /**
           * 是否使用 vitepress 的主题色
           *
           * @default true
           */
          vitepressTheme?: boolean;
          /**
           * 是否使用 elementPlus 的主题色
           *
           * @default true
           */
          elementPlusTheme?: boolean;
        };
    /**
     * 布局默认主题色
     *
     * @default ThemeColorName.vpDefault
     */
    defaultColorName?:
      | ThemeColorName
      | "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;
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204

v1.4.1 如果想去掉主题增强面板主题色的 VitePress 主题色或者 ElementPlus 主题色，可以使用 themeEnhance.themeColor.customize 配置项。

该配置项为 false 时，将关闭 Teek 所有内置的主题色，此时你可以通过 themeEnhance.themeColor.append 自定义添加自己的主题色。
该配置项为 object 时，可以选择关闭 VitePress 主题色或者 ElementPlus 主题色

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

const teekConfig = defineTeekConfig({
  themeEnhance: {
    themeColor: {
      customize: false, // 关闭所有内置主题色

      // 或选择性开启/关闭部分内置主题色
      // customize: {
      //   vitepressTheme: true,
      //   elementPlusTheme: true,
      // },
    },
  },
});

如果想拓展自己的主题色，请看主题增强拓展。

author

文章默认的作者信息。

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

config.mts文章页 xx.md更多配置项

// .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",
---

interface Author {
  /**
   * 作者名称，作用在首页的 PostItem 和文章页
   */
  name: string;
  /**
   * 点击作者名称后跳转的链接
   */
  link?: string;
}

notice

公告配置。

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

使用如下：

// .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),
    });
  },
};

配置如下：

config.mts文章页 xx.md更多配置项

// .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"
---

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 分析

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

使用如下：

config.mts更多配置项

// .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: "**",
      },
    },
  ],
});

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;
};

全局配置 ​

teekTheme ​

teekHome ​

vpHome ​

loading v1.4.1 ​

features v1.4.1 ​

anchorScroll ​

themeSize ​

viewTransition v1.5.0 ​

backTop v1.4.0 ​

toComment v1.4.0 ​

codeBlock ​

sidebarTrigger v1.4.0 ​

windowTransition v1.4.1 ​

bodyBgImg ​

themeEnhance v1.1.0 ​

author ​

notice ​

siteAnalytics ​

全局配置

teekTheme

teekHome

vpHome

loading v1.4.1

features v1.4.1

anchorScroll

themeSize

viewTransition v1.5.0

backTop v1.4.0

toComment v1.4.0

codeBlock

sidebarTrigger v1.4.0

windowTransition v1.4.1

bodyBgImg

themeEnhance v1.1.0

author

notice

siteAnalytics