One

主题

全局配置 ​

全局配置 ​

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

tkTheme ​

  • 类型：boolean
  • 默认值：true

是否启用主题，如果为 false，则不会启用主题的 99% 功能，只保留永久链接、锚点滚动、深色/浅色模式过渡动画这三个功能。支持在首页 index.md 的 frontmatter 配置 tk.tkTheme。

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  tkTheme: true,
});

！

yaml
---
tk:
  tkTheme: false
---

提示

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

tkHome ​

  • 类型：boolean
  • 默认值：true

是否启用 Teeker 的首页风格，如果为 false，则还原到 Vitepress 的默认首页，其他功能不变。支持在首页 index.md 的 frontmatter 配置 tk.tkHome。

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  tkHome: true,
});
yaml
---
tk:
  tkHome: true
---

anchorScroll ​

  • 类型：boolean
  • 默认值：true

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

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  anchorScroll: true,
});
yaml
---
tk:
  anchorScroll: true
---

viewTransition ​

  • 类型：boolean
  • 默认值：true

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

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  viewTransition: true,
});
yaml
---
tk:
  viewTransition: true
---

codeBlock ​

  • 类型：boolean
  • 默认值：true

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

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  codeBlock: true,
});
yaml
---
tk:
  codeBlock: true
---

bodyBgImg ​

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

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  bodyBgImg: {
    imgSrc: ["/img/bg1.jpg", "/img/bg2.png"], // body 背景大图链接。单张图片 string | 多张图片 string[], 多张图片时每隔 imgInterval 秒换一张
    imgOpacity: 1, // body 背景图透明度，选值 0.1 ~ 1.0
    imgInterval: 15000, //  body 当多张背景图时（imgSrc 为数组），设置切换时间，单位：毫秒
    mask: false, // body 背景图遮罩
    maskBg: "rgba(0, 0, 0, 0.2)", // body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
    pageStyle: "default", // 文章页的样式风格，default 为 Vitepress 原生风格，card 为单卡片风格，segment 为片段卡片风格，card-nav 和 segment-nav 会额外修改导航栏样式
  };
});
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 背景图遮罩
   *
   * @default false
   */
  mask?: boolean;
  /**
   * body 背景图遮罩颜色，如果为数字，则是 rgba(0, 0, 0, ${maskBg})，如果为字符串，则作为背景色。mask 为 true 时生效
   *
   * @default 'rgba(0, 0, 0, 0.2)'
   */
  maskBg?: string | number;
  /**
   * 文章页的样式风格，default 为 Vitepress 原生风格，card 为单卡片风格，segment 为片段卡片风格，card-nav 和 segment-nav 会额外修改导航栏样式
   */
  pageStyle?: "default" | "card" | "segment" | "card-nav" | "segment-nav";
}

提示

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

themeSetting ​

右下角的主题设置配置。

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

ts
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  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
import tkThemeConfig from "vitepress-theme-teek/config";

const tkConfig = tkThemeConfig({
  author: {
    name: "天客", // 作者名称
    link: "https://github.com/Kele-Bingtang", // 点击作者名称后跳转的链接
  };
});
ts
interface TkThemeConfig {
  /**
   * 文章默认的作者信息
   */
  author?: {
    /**
     * 作者名称，作用在首页的 PostItem 和文章页
     */
    name: string;
    /**
     * 点击作者名称后跳转的链接
     */
    link?: string;
  };
}

notice ​

公告配置。

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

使用如下：

ts
import tkThemeConfig from "vitepress-theme-teek/config";
import MyNoticeContent from "./components/MyNoticeContent.vue";

const tkConfig = tkThemeConfig({
  notice: {
    render: MyNoticeContent,
  };
});
ts
import Teeker from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import MyNoticeContent from "./components/MyNoticeContent.vue";

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

配置如下：

ts
const tkConfig = tkThemeConfig({
  notice: {
    enabled: true, // 是否启用公告功能
    title: "公告", // 公告标题，支持函数式：需要和国际化搭配使用，根据不同语言环境返回不同标题
    initOpen: true,
    duration: 0, // 弹框定时自动关闭，0 不自动消失
    mobileMinify: false, // 移动端自动最小化
    reopen: true,
    useStorage: true, // 是是否使用 localStorage 存储公告状态，如：当打开公告弹框后，下次进来则自动打开弹框
    twinkle: false, // 公告图标是否打开闪烁提示
    position: "top", // 公告弹框出现位置
    // ...
  },
});
ts
import type { Ref, VNode } 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;
  /**
   * 自定义内容组件，返回一个 VNode，比如一个 vue 组件
   */
  render?: () => VNode;
}