One

主题

全局配置 ​

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

tkTheme ​

  • 类型：boolean
  • 默认值：true

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

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

配置如下：

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

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

提示

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

tkHome ​

  • 类型：boolean
  • 默认值：true

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

支持在首页 index.md 的 frontmatter 配置 tk.tkHome。

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

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

anchorScroll ​

  • 类型：boolean
  • 默认值：true

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

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

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

viewTransition ​

  • 类型：boolean
  • 默认值：true

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

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

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

codeBlock ​

  • 类型：boolean
  • 默认值：true

是否使用新版代码块样式，如果为 false，则使用 Vitepress 默认样式。

支持在文章页的 frontmatter 配置，优先级高于 config 配置。

提示

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

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

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

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

提示

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

先定义一个 css 文件：

tk-theme-style.css
css
/* .vitepress/theme/style/tk-theme-style.css */
:root {
  tk-code-block-lang-transform: none; /* 文本中的单词保持默认风格 */
  tk-code-block-lang-transform: capitalize; /* 文本中的每个单词以大写字母开头 */
  tk-code-block-lang-transform: 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-theme-style.css";

export default {
  extends: Teek,
};

bodyBgImg ​

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

ts
// .vitepress/config.ts
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 时生效
  };
});
ts
interface TkThemeConfig {
  /**
   *  body 背景图片配置
   */
  bodyBgImg?: BodyBgImg;
}

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 时按顺序切换
   */
  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 的图片风格会失效。

themeSetting ​

右下角的主题设置配置。

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

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

const teekConfig = defineTeekConfig({
  author: {
    useThemeStyle: true, // 是否启用主题风格，如果为 false，则不会显示切换按钮
    themeStyle: "vp-default", // 设置当前主题风格
    useThemeSize: true, // 是否使用主题尺寸切换功能
    themeSize: "default", // 设置当前主题尺寸
    // ...
  };
});
ts
interface TkThemeConfig {
  /**
   * 右下角的主题设置配置
   */
  themeSetting?: ThemeSetting;
}

interface ThemeSetting {
  /**
   * 是否启用主题风格，如果为 false，则不会显示切换按钮
   *
   * @default true
   */
  useThemeStyle?: boolean;
  /**
   * 设置当前主题风格
   *
   * @default 'vp-default'
   */
  themeStyle?:
    | "vp-default"
    | "vp-green"
    | "vp-yellow"
    | "vp-red"
    | "el-blue"
    | "el-green"
    | "el-yellow"
    | "el-red"
    | string;
  /**
   * 自定义主题风格，将会追加到内置主题风格后面
   */
  themeStyleAppend?: {
    /**
     * 主题组名称
     */
    label: string;
    /**
     * 主题组提示信息，鼠标悬停时显示
     */
    tip?: string;
    /**
     * 主题组内容
     */
    options: {
      /**
       * 主题名称，用于页面文字渲染
       */
      name: string;
      /**
       * 主题标识，在 html 标签的 theme 属性添加该标识
       */
      theme: string;
    }[];
  }[];
  /**
   * 是否使用主题尺寸切换功能
   *
   * @default true
   */
  useThemeSize?: boolean;
  /**
   * 设置当前主题尺寸
   *
   * @default 'default'
   */
  themeSize?: "small" | "default" | "large" | string;
  /**
   * 自定义主题尺寸，将会追加到内置主题尺寸后面
   */
  themeSizeAppend?: {
    /**
     * 主题尺寸名称，用于页面文字渲染
     */
    name: string;
    /**
     * 主题尺寸标识，在 html 标签的 size 属性添加该标识
     */
    size: string;
  }[];
}

author ​

文章默认的作者信息。

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

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

const teekConfig = defineTeekConfig({
  author: {
    name: "Teeker", // 作者名称
    link: "https://github.com/Kele-Bingtang", // 点击作者名称后跳转的链接
  };
});
ts
interface TkThemeConfig {
  /**
   * 文章默认的作者信息
   */
  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.ts
const teekConfig = defineTeekConfig({
  notice: {
    enabled: true, // 是否启用公告功能
    title: "公告", // 公告标题，支持函数式：需要和国际化搭配使用，根据不同语言环境返回不同标题
    initOpen: true,
    duration: 0, // 弹框定时自动关闭，0 不自动消失
    mobileMinify: false, // 移动端自动最小化
    reopen: true,
    useStorage: true, // 是是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
    twinkle: false, // 公告图标是否打开闪烁提示
    position: "top", // 公告弹框出现位置
    // ...
  },
});
ts
import type { Ref } from "vue";
import type { Route } from "vitepress";

interface TkThemeConfig {
  /**
   * 公告配置
   */
  notice?: Notice;
}

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 配合使用
   *
   * 1、noticeIconType 为 svg 时，需要填写 svg 代码
   * 2、noticeIconType 为 iconfont 时，需要填写 class 名
   * 3、noticeIconType 为 img 时，需要填写图片链接
   * 4、noticeIconType 为 el 时，需要传入 ElIcon 的组件
   */
  noticeIcon?: string;
  /**
   * 图标类型
   *
   * @default 'svg'
   */
  noticeIconType?: "svg" | "iconfont" | "img" | "el";
  /**
   * 公告弹框关闭图标地址，与 noticeIcon 配置一致
   */
  closeIcon?: string;
  /**
   * 图标类型，与 noticeIconType 配置一致
   *
   * @default 'svg'
   */
  closeIconType?: "svg" | "iconfont" | "img" | "el";
  /**
   * 路由切换后的自定义回调
   *
   * @param to 切换到的目标路由
   */
  onAfterRouteChange?: (to: Route, noticeShow: Ref<boolean>, showPopover: Ref<boolean>) => void;
}